summaryrefslogtreecommitdiffstats
path: root/tderesources/README.design
diff options
context:
space:
mode:
Diffstat (limited to 'tderesources/README.design')
-rw-r--r--tderesources/README.design173
1 files changed, 173 insertions, 0 deletions
diff --git a/tderesources/README.design b/tderesources/README.design
new file mode 100644
index 000000000..fc31a2078
--- /dev/null
+++ b/tderesources/README.design
@@ -0,0 +1,173 @@
+tderesources
+README.design
+
+KDE RESOURCES
+-------------
+The KDE Resource framework can be used to manage resources of
+different types, organized in families. The Resource framework is
+currently used for addressbook resources in tdelibs/kabc and for
+calendar resources in libkcal.
+A resource family represents stores of information of a certain kind
+(appointments, contacts). A resource type class represents a way in
+which this information is stored, or a way to access the information.
+
+ resources
+ |
+ +----------+----------+----------------+---
+ | | |
+Families: calendar contacts ...
+ | |
+ +---+--+ +-----+-----+-----+--
+ | | | | | |
+Types: local Exchange file dir ldap ...
+ file server
+
+
+Resource families are usually implemented as (abstract) classes
+in a library, e.g. the calendar resource in libkcal en the
+addressbook resource family in libkabc. Resource type are like
+plugins: that can be loaded on-demand, they are implemented in
+their own library, and a .desktop file tells KDE where to find
+them.
+
+The user then configures one or more resources for a certain
+family, making use of the resource types. For instance, a user
+might define two Exchange-based resources, one with her own
+calendar data and one with the calendar data of her workgroup.
+She might also have two ldap contacts resources, together with
+a local file-based address book.
+
+Both Exchange-based calendar resources are objects of the same
+type, but with different settings. These resources are persistent,
+and they are managed by the ResourceManager for the calendar
+resource family. The list of resources, and the settings for
+each resource, are stored by the resource manager using TDEConfig,
+in $HOME/.trinity/share/config/<family>.
+
+The resource manager is a singleton object for every resource family.
+Use the resource manager to get the list of available resource types
+in this family, to create a new resource of a given type, to get a
+configuration widget for a resource, to get the list of defined
+resources in this family, and to get a specific resource object.
+
+USE CASES
+---------
+Opening all resources of resource family "calendar". The associated
+(abstract) class is ResourceCalendar.
+
+ KRES::ResourceManager<ResourceCalendar> mManager = new KRES::ResourceManager<ResourceCalendar>( "calendar" );
+ QPtrList<ResourceCalendar> mResources = mManager->resources();
+ // Open resources
+ ResourceCalendar *resource;
+ for ( resource = mResources.first(); resource; resource = mResources.next() ) {
+ kdDebug() << "Opening resource " + resource->name() << endl;
+ bool result = resource->open();
+ if ( ! result )
+ kdDebug() << "Error opening resource" << endl;
+ }
+
+Note that the resources are configured by the user in a kcontrol
+applet. The singleton resourcemanager reads the configuration from
+the config file that the kcm applet writes.
+
+Getting the events for a certain date range from all resources.
+ResourceCalendar defines a function
+QPtrList<Event> rawEvents( QDate start, QDate end, bool inclusive )
+that returns the events in the resource in the date range. We just
+iterate over all available resources to harvest all events.
+
+ QPtrList<Event> result;
+ ResourceCalendar *resource;
+ for ( resource = mResources.first(); resource; resource = mResources.next() ) {
+ QPtrList<Event> list = resource->rawEvents( start, end, inclusive );
+ Event* item;
+ for ( item = list.first(); item; item = list.next() ) {
+ result.append( item );
+ }
+ }
+
+EXAMPLES
+--------
+For examples, check the following files in tdepim/libkcal:
+- resourcecalendar.{h,cpp}
+ Defines the base class of the calendar resource family
+- kcmcalendars.{h,cpp}
+ Defines the KControl applet for calendar resources
+- kcalendars.desktop
+ This .desktop files tells KControl where to find the
+ applet for calendar resources.
+- Makefile.am
+ How to build and install the calendar resource family
+
+The "local" resource is compiled and installed together
+with libkcal:
+- resourcelocal.{h,cpp}
+ Defines the local resource type, in the calendar resource family
+- resourcelocalconfig.{h,cpp}
+ Defines the configuration widget for the local resource
+- local.desktop
+ Information on the local resource type, in order to know
+ which resource types are available
+
+The "exchange" calendar resource is compiled in a separate
+library, dynamically loaded by the resource manager if
+resources of this type are used. This resource is in
+tdepim/tderesources/exchange:
+- resourceexchange.{h,cpp}
+ Defines the exchange resource
+- resourceexchangeconfig.{h,cpp}
+ Defines the configuration widget for the exchange resource
+- exchange.desktop
+ This file is installed so that the resource manager can
+ find the exchange resource type
+- Makefile.am
+ How to build and install the exchange resource type
+
+IDEAS/ISSUES/PROBLEMS
+---------------------
+- What happens when there are resource manager in two separate
+processes (like kcontrol and korganizer, or two kcontrols) both
+accessing the same resource family?
+
+ + If there are more than one resource managers running in the
+ same KDE session, but in separate processes, they should keep
+ each other informed. I've implemented some DCOP stuff so that
+ the various managers know when resources have been added,
+ deleted or modified. These messages are not yet handled
+ completely.
+
+- The resource manager should send a signal when a resource
+has changed, so that the applications can update their information.
+
+ + Problem with this: ResourceManager is a template class.
+ Templates cannot have signals or slots. An app should
+ implement the ManagerObserver interface and register with the
+ resource manager.
+
+- Maybe the flags that marks each resource as active or passive,
+and the Standard resource, should be application-specific? E.g.,
+I can imagine karm looking only in the business calendar, so it
+should have only one active calendar, while KORganizer would also
+have my wife's calendar active read-only.
+
+- There should be a way to synchronize the concurrent use of a
+resource, be it in the same process, on different processes in
+the same KDE session, or even when e.g. korganizer uses an
+Exchange calendar while also Outlook is running on a Windows PC.
+
+- have the item that resource object delivers (events, contacts)
+derived from ResourceItem. Then introduce locking and unlocking,
+that every resource type should extend using its own locking
+mechanism, like SQL locks, or file locks, or whatever.
+
+ + This means that Addressee, Event etc. should be
+ derived from ResourceItem.
+ + Communication via DCOP via the Resource, I think.
+ + Drawback: flexibility is lost, because the Resource
+ would have to be a factory for these objects.
+
+- Maybe the resource class should have some generic support
+for searching. In the calendar family, you could search by
+date, by category or by key word, in the kabc family you
+could search by key word, name, country, etc.
+