You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
174 lines
7.1 KiB
174 lines
7.1 KiB
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/tdeabc 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 libtdeabc. 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 tdeabc family you
|
|
could search by key word, name, country, etc.
|
|
|