[KLF Application][KLF Tools][KLF Backend][KLF Home]
KLatexFormula Project
Classes | Public Types | Public Slots | Signals | Public Member Functions | Protected Types | Protected Member Functions | List of all members
KLFLibResourceEngine Class Referenceabstract

An abstract resource engine. More...

#include <klflib.h>

Inheritance diagram for KLFLibResourceEngine:
Inheritance graph
[legend]
Collaboration diagram for KLFLibResourceEngine:
Collaboration graph
[legend]

Classes

struct  KLFLibEntryWithId
 A KLFLibEntry in combination with a KLFLib::entryId. More...
 
struct  Query
 A structure that describes a query for query() More...
 
struct  QueryResult
 A structure that will hold the result of a query() query. More...
 

Public Types

enum  ResourceProperty { PropTitle = 0, PropLocked, PropViewType, PropAccessShared }
 
enum  SubResourceProperty { SubResPropTitle = 0, SubResPropLocked = 1, SubResPropViewType = 2 }
 
enum  ResourceFeature {
  FeatureReadOnly = 0x0001, FeatureLocked = 0x0002, FeatureSaveTo = 0x0004, FeatureSubResources = 0x0008,
  FeatureSubResourceProps = 0x0010
}
 Features that may or may not be implemented by subclasses. More...
 
enum  WantUrlFormatFlag { WantUrlDefaultSubResource = 0x01, WantUrlReadOnly = 0x02 }
 Format options one can give to url() More...
 
enum  ModifyType {
  AllActionsData = 0, UnknownModification = 0, InsertData, ChangeData,
  DeleteData
}
 
typedef KLFLib::entryId entryId
 
- Public Types inherited from KLFPropertizedObject
enum  ToStringFlag
 

Public Slots

virtual bool setTitle (const QString &title)
 set a new resource title for this library resource More...
 
virtual bool setLocked (bool locked)
 Set the resource to be locked. More...
 
virtual bool setViewType (const QString &viewType)
 
virtual bool setReadOnly (bool readonly)
 Set the resource to be read-only or not. More...
 
virtual void setDefaultSubResource (const QString &subResource)
 Set the default sub-resource. More...
 
virtual bool createSubResource (const QString &subResource, const QString &subResourceTitle)
 Create a new sub-resource. More...
 
virtual bool createSubResource (const QString &subResource)
 Create a new sub-resource. More...
 
virtual bool renameSubResource (const QString &oldSubResourceName, const QString &newSubResourceName)
 
virtual bool deleteSubResource (const QString &subResource)
 
virtual bool setSubResourceProperty (const QString &subResource, int propId, const QVariant &value)
 
virtual entryId insertEntry (const QString &subResource, const KLFLibEntry &entry)
 Insert an entry into this resource. More...
 
virtual entryId insertEntry (const KLFLibEntry &entry)
 Insert an entry into this resource. More...
 
virtual QList< entryIdinsertEntries (const QString &subResource, const KLFLibEntryList &entrylist)=0
 Insert new entries in this resource. More...
 
virtual QList< entryIdinsertEntries (const KLFLibEntryList &entrylist)
 Insert new entries in this resource. More...
 
virtual bool changeEntries (const QString &subResource, const QList< entryId > &idlist, const QList< int > &properties, const QList< QVariant > &values)=0
 Change some entries in this resource. More...
 
virtual bool changeEntries (const QList< entryId > &idlist, const QList< int > &properties, const QList< QVariant > &values)
 Change some entries in this resource. More...
 
virtual bool deleteEntries (const QString &subResource, const QList< entryId > &idlist)=0
 Delete some entries in this resource. More...
 
virtual bool deleteEntries (const QList< entryId > &idList)
 Delete some entries in this resource. More...
 
virtual bool saveTo (const QUrl &newPath)
 
virtual bool setResourceProperty (int propId, const QVariant &value)
 Set a resource property to the given value. More...
 
virtual bool loadResourceProperty (const QString &propName, const QVariant &value)
 Set the given property to the given value. More...
 

Signals

void dataChanged (const QString &subResource, int modificationType, const QList< KLFLib::entryId > &entryIdList)
 Emitted when data has changed. More...
 
void defaultSubResourceChanged (const QString &newDefaultSubResource)
 Emitted when the default sub-resource changes. More...
 
void resourcePropertyChanged (int propId)
 Emitted when a resource property changes. More...
 
void subResourcePropertyChanged (const QString &subResource, int propId)
 Emitted when a sub-resource property changes. More...
 
void subResourceCreated (const QString &newSubResource)
 Emitted when a sub-resource is created. More...
 
void subResourceRenamed (const QString &oldSubResourceName, const QString &newSubResourceName)
 Emitted when a sub-resource is renamed. More...
 
void subResourceDeleted (const QString &subResource)
 Emitted when a sub-resource is deleted. More...
 
void operationStartReportingProgress (KLFProgressReporter *progressReporter, const QString &descriptiveText)
 

Public Member Functions

 KLFLibResourceEngine (const QUrl &url, uint supportedfeatureflags, QObject *parent=NULL)
 
virtual ~KLFLibResourceEngine ()
 
virtual uint supportedFeatureFlags () const
 List of features supported by this resource engine. More...
 
virtual QUrl url (uint flags=0x0) const
 query URL More...
 
virtual uint compareUrlTo (const QUrl &other, uint interestFlags=0xfffffff) const =0
 Compare this resource's URL with another's. More...
 
virtual bool isReadOnly () const
 query read-only state More...
 
virtual QString title () const
 The human-set title of this resource. More...
 
virtual bool locked () const
 Is this resource is locked? More...
 
virtual QString viewType () const
 The (last) View Type used to display this resource. More...
 
virtual bool accessShared () const
 If the resource is accessed by many clients. More...
 
virtual QVariant resourceProperty (const QString &name) const
 Get the value of a resource property. More...
 
virtual bool canModifyData (const QString &subResource, ModifyType modifytype) const
 
virtual bool canModifyData (ModifyType modifytype) const
 
virtual bool canModifyProp (int propId) const
 
virtual bool canRegisterProperty (const QString &propName) const
 
virtual QString suggestedViewTypeIdentifier () const
 
virtual bool hasSubResource (const QString &subResource) const
 
virtual QStringList subResourceList () const
 
virtual QString defaultSubResource () const
 
virtual bool compareDefaultSubResourceEquals (const QString &subResourceName) const
 Compare our sub-resource name to another. More...
 
virtual bool canCreateSubResource () const
 
virtual bool canRenameSubResource (const QString &subResource) const
 
virtual bool canDeleteSubResource (const QString &subResource) const
 
virtual QVariant subResourceProperty (const QString &subResource, int propId) const
 
virtual QList< int > subResourcePropertyIdList () const
 
virtual QString subResourcePropertyName (int propId) const
 
virtual bool canModifySubResourceProperty (const QString &subResource, int propId) const
 
virtual KLFLibEntry entry (const QString &subResource, entryId id)=0
 query an entry in this resource More...
 
virtual KLFLibEntry entry (entryId id)
 query an entry in this resource More...
 
virtual bool hasEntry (const QString &subResource, entryId id)=0
 query the existence of an entry in this resource More...
 
virtual bool hasEntry (entryId id)
 query the existence of an entry in this resource More...
 
virtual QList< KLFLibEntryWithIdentries (const QString &subResource, const QList< KLFLib::entryId > &idList, const QList< int > &wantedEntryProperties=QList< int >())=0
 query multiple entries in this resource More...
 
virtual QList< KLFLibEntryWithIdentries (const QList< KLFLib::entryId > &idList, const QList< int > &wantedEntryProperties=QList< int >())
 query multiple entries in this resource More...
 
virtual int query (const QString &subResource, const Query &query, QueryResult *result)=0
 query entries in this resource with specified property values More...
 
virtual QList< QVariantqueryValues (const QString &subResource, int entryPropId)=0
 List all distinct values that a property takes in all entries. More...
 
virtual QList< KLFLib::entryIdallIds (const QString &subResource)=0
 Returns all IDs in this resource (and this sub-resource) More...
 
virtual QList< KLFLib::entryIdallIds ()
 Returns all IDs in this resource (and the default sub-resource) More...
 
virtual QList< KLFLibEntryWithIdallEntries (const QString &subResource, const QList< int > &wantedEntryProperties=QList< int >())=0
 query all entries in this resource More...
 
virtual QList< KLFLibEntryWithIdallEntries (const QList< int > &wantedEntryProperties=QList< int >())
 query all entries in this resource More...
 
void blockProgressReportingForNextOperation ()
 Specifies that the next operation (only) should not report progress. More...
 
void blockProgressReporting (bool block)
 (Un)Blocks generally progress reporting More...
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent=0)
 
 blockSignals (bool block)
 
 childEvent (QChildEvent *event)
 
 children ()
 
 connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type=Qt::AutoCompatConnection)
 
 connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type=Qt::AutoCompatConnection)
 
 connectNotify (const char *signal)
 
 customEvent (QEvent *event)
 
 deleteLater ()
 
 destroyed (QObject *obj=0)
 
 disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
 disconnect (const char *signal=0, const QObject *receiver=0, const char *method=0)
 
 disconnect (const QObject *receiver, const char *method=0)
 
 disconnectNotify (const char *signal)
 
 dumpObjectInfo ()
 
 dumpObjectTree ()
 
 dynamicPropertyNames ()
 
 event (QEvent *e)
 
 eventFilter (QObject *watched, QEvent *event)
 
 findChild (const QString &name=QString()
 
 findChildren (const QString &name=QString()
 
 findChildren (const QRegExp &regExp)
 
 inherits (const char *className)
 
 installEventFilter (QObject *filterObj)
 
 isWidgetType ()
 
 killTimer (int id)
 
 metaObject ()
 
 moveToThread (QThread *targetThread)
 
 parent ()
 
 property (const char *name)
 
 receivers (const char *signal)
 
 removeEventFilter (QObject *obj)
 
 sender ()
 
 setParent (QObject *parent)
 
 setProperty (const char *name, const QVariant &value)
 
 signalsBlocked ()
 
 startTimer (int interval)
 
 thread ()
 
 timerEvent (QTimerEvent *event)
 
 tr (const char *sourceText, const char *comment=0, int n=-1)
 
 trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
 
 staticMetaObject
 
 QObject (QObject *parent, const char *name)
 
 checkConnectArgs (const char *signal, const QObject *object, const char *method)
 
 child (const char *objName, const char *inheritsClass=0, bool recursiveSearch=true)
 
 className ()
 
 insertChild (QObject *object)
 
 isA (const char *className)
 
 name ()
 
 name (const char *defaultName)
 
 normalizeSignalSlot (const char *signalSlot)
 
 removeChild (QObject *object)
 
 setName (const char *name)
 
- Public Member Functions inherited from KLFPropertizedObject
 KLFPropertizedObject (const QString &propertyNameSpace)
 
virtual ~KLFPropertizedObject ()
 
virtual QVariant property (const QString &propName) const
 
virtual QVariant property (int propId) const
 
QList< int > propertyIdList () const
 
QStringList propertyNameList () const
 
QMap< QString, QVariantallProperties () const
 
void setAllProperties (const QMap< QString, QVariant > &propValues)
 
QByteArray allPropertiesToByteArray () const
 
void setAllPropertiesFromByteArray (const QByteArray &data)
 
virtual QString toString (uint toStringFlags=0) const
 
int propertyMaxId () const
 
bool propertyIdRegistered (int propId) const
 
bool propertyNameRegistered (const QString &propertyName) const
 
int propertyIdForName (const QString &propertyName) const
 
QString propertyNameForId (int propId) const
 
QList< int > registeredPropertyIdList () const
 
QStringList registeredPropertyNameList () const
 
QMap< QString, int > registeredProperties () const
 

Protected Types

enum  ModifyStatus { MS_CanModify = 0, MS_IsLocked = 1, MS_SubResLocked = 2, MS_NotModifiable = 3 }
 

Protected Member Functions

virtual bool saveResourceProperty (int propId, const QVariant &value)=0
 Save a resource property to the backend resource data. More...
 
virtual ModifyStatus baseCanModifyStatus (bool inSubResource, const QString &subResource=QString()) const
 can modify data in resource (base common tests only) More...
 
bool thisOperationProgressBlocked () const
 
- Protected Member Functions inherited from KLFPropertizedObject
virtual void propertyValueChanged (int propId, const QVariant &oldValue, const QVariant &newValue)
 
virtual void setProperty (const QString &propname, const QVariant &value)
 
virtual void setProperty (int propId, const QVariant &value)
 
virtual int loadProperty (const QString &propname, const QVariant &value)
 
void registerBuiltInProperty (int propId, const QString &propName) const
 
int registerProperty (const QString &propertyName) const
 
QString propertyNameSpace () const
 
QVector< QVariantpropertyVector () const
 

Additional Inherited Members

- Static Protected Member Functions inherited from KLFPropertizedObject
static void registerBuiltInProperty (const QString &propNameSpace, int propId, const QString &name)
 
static int registerProperty (const QString &propNameSpace, const QString &propertyName)
 
static int propertyMaxId (const QString &propNameSpace)
 
static bool propertyIdRegistered (const QString &propNameSpace, int propId)
 
static bool propertyNameRegistered (const QString &propNameSpace, const QString &propertyName)
 
static int propertyIdForName (const QString &propNameSpace, const QString &propertyName)
 
static QString propertyNameForId (const QString &propNameSpace, int propId)
 
static QList< int > registeredPropertyIdList (const QString &propNameSpace)
 
static QStringList registeredPropertyNameList (const QString &propNameSpace)
 
static QMap< QString, int > registeredProperties (const QString &propNameSpace)
 

Detailed Description

An abstract resource engine.

This class is the base of all resource types. Subclasses (e.g. KLFLibDBEngine) implement the actual access to the data, while this class defines the base API that will be used by e.g. the library browser (through a KLFAbstractLibView subclass) to access the data.

Subclasses may choose to implement various features specified by the ResourceFeature enum. The supported features must be passed (binary OR-ed) to the constructor.

Library resources provide entries without any particular order.

Library entries are communicated with KLFLibEntry objects. Each entry in the resource must be attributed a numerical ID, which is unique within the resource, in particular not necessarily globally unique among all open resources. For engines implementing the FeatureSubResources feature, the attributed IDs have only to be unique within the sub-resource the entry lives in.

Entries are queried by calling for example the functions: allEntries(), entries(), entry(). See the individual function documentation for more details.

The API in this class for accessing data is pretty elaborate. You may consider to subclass KLFLibResourceSimpleEngine, which requires you to implement a simpler API, but at the price of not being able to take profit of the optimization opportunities given by the more complicated API.

Resource Properties. Resources have properties (stored in a KLFPropertizedObject structure, NOT in regular QObject properties) that ARE STORED IN THE RESOURCE DATA ITSELF. Built-in properties are listed in the ResourceProperty enum. Some properties may be implemented read-only (eg. PropAccessShared) in which case saveResourceProperty() should return FALSE.

The view used to display this resource is stored in the "ViewType" resource property (and thus should be stored in the backend data like other properties).

Note on URL. The URL is not a resource property as it is not stored in the resource itself. However the resource engine instance knows about the url it is manipulating (because subclasses pass the relevant url as parameter in the constructor). However, the URL itself blindly stored and reprovided when requested; it is not used by KLFLibResourceEngine itself. Small exception: in the constructor, some query items are recognized and stripped from the URL. See below.

Read-Only Mode. The read-only mode differs from the locked property in that the mode is activated by the accessor only and is NOT stored in the resource data eg. on disk (in contrast to the locked property). It is up to SUBCLASSES to enforce this flag and prevent data from being modified if isReadOnly() is TRUE.
Subclasses may prevent read-only mode by not specifying the FeatureReadOnly in the constructor. In this case the default implementation of setReadOnly() will return FALSE without doing anything. Also in this case, any occurrence of the query item "klfReadOnly" in the URL is stripped and ignored.

Sub-Resources. Sub-resources are a way of logically separating the contents of a resource into separate so-called "sub-resources", like for example a library could contain a sub-resource "History", "Archive" etc. Derived subclasses don't have to implement subresources, they can specify if subresources are available using the FeatureSubResources flag in the constructor. In classes implementing sub-resources, the default sub-resource (queried by defaultSubResource() and set by setDefaultSubResource()) is the resource that the insertEntry(), changeEntries(), etc. family functions will access when the variant of the function without sub-resource argument is called.

Sub-Resource Properties. Sub-resources, when implemented by the subclass, may each have properties (the API would suggest subclasses to store these property values into KLFPropertizedObject's). The properties (structure+values) are NOT stored by KLFLibResourceEngine itself, all the work must be done by the subclass, in particular reimplementing subResourceProperty() and setSubResourceProperty(). Again this feature is implemented by the subclass if and only if the subclass specified FeatureSubResourceProps in the constructor argument. In this case note also that views may for example expect the resource to provide values for the sub-resource properties defined by SubResourceProperty.

query Items in URL. The URL may contain query items e.g. scheme://klf.server.dom/path/to/location?klfReadOnly=true. Here is a list of recognized (universal) query items. Subclasses may choose to recognize more query items, but these listed here are detected in the KLFLibResourceEngine constructor and the appropriate flags are set (eg. isReadOnly()):

Note that recognized query items (and only the query items recognized at the KLFLibResourceEngine level) are stripped from the url() as they are parsed. Subclasses may choose to (independently) recognize and strip other query items from URL if it is relevant to do so.

NOTES FOR SUBCLASSES

Definition at line 440 of file klflib.h.

Member Typedef Documentation

Definition at line 444 of file klflib.h.

Member Enumeration Documentation

Whether it's possible to modify something (data, property value, etc.)

Enumerator
MS_CanModify 

It's possible to modify that something.

MS_IsLocked 

That something is resource-locked (ie., the only possible action is to unlock it)

MS_SubResLocked 

That something is sub-resource-locked.

MS_NotModifiable 

That something is read-only or not modifiable for another reason.

Definition at line 1517 of file klflib.h.

Enumerator
AllActionsData 
UnknownModification 
InsertData 
ChangeData 
DeleteData 

Definition at line 633 of file klflib.h.

Features that may or may not be implemented by subclasses.

These binary codes specify features that a subclass may or may not implement.

The subclass provides the binary combination of the exact features it supports in the constructor argument in KLFLibResourceEngine().

The flags can be accessed with a call to supportedFeatureFlags(). They cannot be modified after the constructor call.

See this class documentation for more details.

Enumerator
FeatureReadOnly 

Open in Read-Only mode.

Flag indicating that this resource engine supports opening a location in read-only mode. This resource explicitely checks that we're not isReadOnly() before modifying the resource contents.

FeatureLocked 

Lock the resource.

Flag indicating that this resource engine supports the resource property PropLocked, can modify that property and checks that we're not locked() before modifying the resource contents.

Resources supporting feature FeatureSubResourceProps, in combination with this feature (FeatureLocked) are also expected to treat properly locked sub-resources (ie. sub-resource property SubResPropLocked).

FeatureSaveTo 

Implements the saveTo() function.

Flag indicating that this resource engine implements the saveTo() function, ie. that calling it has a chance that it will not fail

FeatureSubResources 

Data can be stored in separate sub-resources.

Flag indicating that this resource engine supports saving and reading data into different "sub-resources". See class documentation for details.

FeatureSubResourceProps 

Sub-Resources may be assigned properties and values.

Flag indicating that this resource engine supports saving and reading sub-resource property values. This flag makes sense only in combination with FeatureSubResources. Note that views may assume that implementing sub-resource properties means also providing sensible values and/or loaded/stored values for the built-in sub-resource properties described in the SubResourceProperty enum.

Definition at line 486 of file klflib.h.

List of built-in KLFPropertizedObject-properties. See class documentation and setResourceProperty().

Enumerator
PropTitle 
PropLocked 
PropViewType 
PropAccessShared 

Definition at line 456 of file klflib.h.

List of pre-defined properties that can be applied to sub-resources when the features FeatureSubResources and FeatureSubResourceProps are implemented. See also setSubResourceProperty().

Note
These properties, by contrast to resource properties, have fixed numerical IDs, since sub-resource properties are not backed by a KLFPropertizedObject object.
Enumerator
SubResPropTitle 
SubResPropLocked 
SubResPropViewType 

Definition at line 469 of file klflib.h.

Format options one can give to url()

Enumerator
WantUrlDefaultSubResource 

Add a query item for default sub-res. as "klfDefaultSubResource".

WantUrlReadOnly 

Add a query item for read-only status, as "klfReadOnly".

Definition at line 553 of file klflib.h.

Constructor & Destructor Documentation

KLFLibResourceEngine::KLFLibResourceEngine ( const QUrl url,
uint  supportedfeatureflags,
QObject parent = NULL 
)
Note
If the URL url needs to be normalized in some way (eg. convert some query item values to lower case, ...), then you need to implement a static function, eg.
static KLFMyEngine * openURL(const QUrl& url) {
QUrl normalized = url;
// ... normalize URL ...
return new KLFMyEngine(normalized, ...);
}
KLFMyEngine::KLFMyEngine(const QUrl& url, ...) : KLFLibResourceEngine(url,...)
{
// ...
}
which will pass the normalized URL here. You cannot change the URL once it has been passed to the constructor. Note however that the stored URL has some elements stripped, as described in the class documentation KLFLibResourceEngine, which you can change via the API (eg. setDefaultSubResource()).

Definition at line 416 of file klflib.cpp.

References QUrl::allQueryItemValues(), FeatureReadOnly, FeatureSubResources, and QUrl::removeAllQueryItems().

KLFLibResourceEngine::~KLFLibResourceEngine ( )
virtual

Definition at line 443 of file klflib.cpp.

Member Function Documentation

virtual bool KLFLibResourceEngine::accessShared ( ) const
inlinevirtual

If the resource is accessed by many clients.

Whether the resource is meant to be shared by many clients (eg. a remote database access) or if it is local and we're the only one to use it (eg. a local sqlite file).

This property may be used by views to decide if they can store meta-information about the view state in the resource itself (icon positions in icon view mode for example).

Definition at line 622 of file klflib.h.

References KLFPropertizedObject::property(), and QVariant::toBool().

virtual QList<KLFLibEntryWithId> KLFLibResourceEngine::allEntries ( const QString subResource,
const QList< int > &  wantedEntryProperties = QList< int >() 
)
pure virtual

query all entries in this resource

Returns all the entries in this library resource (in sub-resource subResource if FeatureSubResources is supported) with their corresponding IDs.

Note
Subclasses must reimplement this function to behave as described here.

Implemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Referenced by allEntries(), KLFMainWin::loadLibrary(), KLFLibResourceSimpleEngine::queryImpl(), KLFLibResourceSimpleEngine::queryValuesImpl(), and KLFLibBrowser::slotExport().

QList< KLFLibResourceEngine::KLFLibEntryWithId > KLFLibResourceEngine::allEntries ( const QList< int > &  wantedEntryProperties = QList<int>())
virtual

query all entries in this resource

Returns all the entries in this library resource (in default sub-resource if FeatureSubResources is supported) with their corresponding IDs.

The default implementation calls allEntries(const QString& subResource, const QList<int>&) with the default subresource as argument. See setDefaultSubResource().

Definition at line 637 of file klflib.cpp.

References allEntries(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

virtual QList<KLFLib::entryId> KLFLibResourceEngine::allIds ( const QString subResource)
pure virtual

Returns all IDs in this resource (and this sub-resource)

Returns a list of the ID of each entry in this resource.

If sub-resources are supported, then returns only IDs in the given subResource. Otherwise, the subResource parameter should be ignored.

Implemented in KLFLibResourceSimpleEngine, and KLFLibDBEngine.

QList< KLFLib::entryId > KLFLibResourceEngine::allIds ( )
virtual

Returns all IDs in this resource (and the default sub-resource)

Returns a list of the ID of each entry in this resource.

If sub-resources are supported, then returns only IDs in the default sub-resource given by defaultSubResource().

The base implementation calls allIds(const QString&) with the default sub-resource as parameter. Subclasses need not reimplement this function, but rather allIds(const QString&) instead.

Definition at line 642 of file klflib.cpp.

References KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

KLFLibResourceEngine::ModifyStatus KLFLibResourceEngine::baseCanModifyStatus ( bool  inSubResource,
const QString subResource = QString() 
) const
protectedvirtual

can modify data in resource (base common tests only)

External classes: Don't call this function directly, use canModifyData(), canModifyProp(), and canModifySubResourceProperty() instead.

Internal classes: this is useful for reimplementations of canModifyData(), canModifyProp(), etc.

The latter and their reimplementations may call this function.

This function can be reimplemented to take into account more factors (eg. a file being writable).

Returns
one value of the ModifyStatus enum. See that documentation for more info.

All supporting-feature checks are made correspondingly as needed. If nothing is supported (read-only, locked, sub-resource properties) by default data is modifiable.

Definition at line 752 of file klflib.cpp.

References FeatureLocked, FeatureReadOnly, FeatureSubResourceProps, FeatureSubResources, isReadOnly(), locked(), MS_CanModify, MS_IsLocked, MS_NotModifiable, MS_SubResLocked, subResourceProperty(), and SubResPropLocked.

Referenced by KLFLibDBEngine::canCreateSubResource(), KLFLibDBEngine::canDeleteSubResource(), canModifyData(), canModifyProp(), and canModifySubResourceProperty().

void KLFLibResourceEngine::blockProgressReporting ( bool  block)

(Un)Blocks generally progress reporting

Definition at line 654 of file klflib.cpp.

Referenced by _klf_block_progress_blocker::_klf_block_progress_blocker(), and _klf_block_progress_blocker::~_klf_block_progress_blocker().

void KLFLibResourceEngine::blockProgressReportingForNextOperation ( )

Specifies that the next operation (only) should not report progress.

Definition at line 648 of file klflib.cpp.

bool KLFLibResourceEngine::canCreateSubResource ( ) const
virtual

Returns TRUE if we can create a new sub-resource in this resource.

This function can be reimplemented if the resource supports feature FeatureSubResources.

The default implementation returns FALSE.

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 514 of file klflib.cpp.

Referenced by KLFLibBrowser::slotRefreshResourceActionsEnabled().

bool KLFLibResourceEngine::canDeleteSubResource ( const QString subResource) const
virtual

Returns TRUE if we can completely delete sub-resource subResource from the resource.

If this function returns FALSE, a subsequent call to deleteSubResoruce() is certain to fail.

The default implementation returns FALSE.

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 523 of file klflib.cpp.

Referenced by KLFLibBrowser::slotRefreshResourceActionsEnabled().

bool KLFLibResourceEngine::canModifyData ( const QString subResource,
ModifyType  modifytype 
) const
virtual

Returns TRUE here if it is possible to modify the resource's data in the way described by modifytype (see ModifyType enum).

Engines supporting feature FeatureSubResources should return TRUE or FALSE whether it is possible to perform the requested action in the given sub-resource subResource. Other engines should ignore the subResource parameter.

For engines supporting all of FeatureSubResources, FeatureSubResourceProps, and FeatureLocked the default implementation checks whether the sub-resource is locked by querying subResourceProperty(SubResPropLocked).

modifytype must be one of AllActionsData, InsertData, ChangeData, DeleteData.

The base implementation returns TRUE only if the current resource is not read-only (see isReadOnly()) and is not locked (see locked()). Subclasses should reimplement this function to add more sophisticated behaviour, eg. checking that an open file is not read-only, or that a DB user was granted the correct rights, etc.

Warning
subclasses should call the base implementation to e.g. take into account eg. the locked() property. If the base implementation returns FALSE, then the subclasses should also return FALSE.

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 472 of file klflib.cpp.

References baseCanModifyStatus(), and MS_CanModify.

Referenced by KLFLibDBEngine::canModifyData(), KLFLibLegacyEngine::canModifyData(), canModifyData(), KLFLibBrowser::displayTitle(), KLFLibModel::dropFlags(), KLFLibModel::dropMimeData(), KLFLibModel::flags(), KLFLibBrowser::openResource(), KLFLibBrowser::showEvent(), KLFLibBrowser::slotCut(), KLFLibBrowser::slotDeleteSelected(), KLFLibBrowser::slotEntriesSelected(), KLFLibBrowser::slotShowContextMenu(), and KLFLibBrowser::slotUpdateForResourceProperty().

bool KLFLibResourceEngine::canModifyData ( ModifyType  modifytype) const
virtual

This function is provided for convenience for resource not implementing FeatureSubResources, or Views relying on the default sub-resource.

Warning
Subclasses should normally not reimplement this function, but rather the canModifyData(const QString&, ModifyType) function, even if they do not support sub-resources!

The default implementation of this function (which should be sufficient in a vast majority of cases) calls

as one would expect.

Definition at line 478 of file klflib.cpp.

References canModifyData(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

bool KLFLibResourceEngine::canModifyProp ( int  propId) const
virtual

Subclasses should return TRUE here if it is possible to modify the resource's property identified by propId. Return for ex. false when opening a read-only file.

Warning
subclasses should call the base implementation to e.g. take into account the locked() property and isReadOnly() state. If the base implementation returns FALSE, then the subclasses should also return FALSE.

If propId is negative, then a more general "Can we generally speaking modify properties right now?" is returned.

Note
The base implementation returns TRUE if the resource is locked but if propId is PropLocked (to be able to un-lock the resource!)

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 485 of file klflib.cpp.

References baseCanModifyStatus(), MS_CanModify, MS_IsLocked, and PropLocked.

Referenced by KLFLibDBEngine::canModifyProp(), KLFLibLegacyEngine::canModifyProp(), setResourceProperty(), KLFLibBrowser::slotRefreshResourceActionsEnabled(), KLFLibBrowser::slotResourceRename(), and KLFLibResPropEditor::updateResourceProperties().

bool KLFLibResourceEngine::canModifySubResourceProperty ( const QString subResource,
int  propId 
) const
virtual

Returns TRUE if the property propId in sub-resource subResource can be modified.

This function should not be called or reimplemented for classes not supporting feature FeatureSubResourceProps.

The default implementation provides a basic functionality based on baseCanModifyStatus(). If the modifiable status of the sub-resource subResource is MS_CanModify, or if the status is MS_IsLocked but the propId we want to modify is SubResPropLocked, this function returns TRUE. In other cases it returns FALSE.

In short, it behaves as you would expect it to: protect against modifications but allow un-locking of a locked sub-resource.

Definition at line 548 of file klflib.cpp.

References baseCanModifyStatus(), MS_CanModify, MS_SubResLocked, and SubResPropLocked.

Referenced by KLFLibBrowser::slotRefreshResourceActionsEnabled(), KLFLibBrowser::slotResourceRename(), and KLFLibResPropEditor::updateSubResourceProperties().

bool KLFLibResourceEngine::canRegisterProperty ( const QString propName) const
virtual

Subclasses should return TRUE if they can handle a new resource property that they (maybe) haven't yet heard of, and if they can handle saving and loading the property as a QVariant to and from the backend data.

Call loadResourceProperty() to actually register the property and save a value to it.

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 491 of file klflib.cpp.

Referenced by loadResourceProperty().

bool KLFLibResourceEngine::canRenameSubResource ( const QString subResource) const
virtual

Returns TRUE if we can give the sub-resource subResource a new name. More specifically, returns TRUE if renameSubResource() on that sub-resource has chances to succeed.

This function can be reimplemented if the resource supports feature FeatureSubResources.

The default implementation returns FALSE.

Reimplemented in KLFLibLegacyEngine.

Definition at line 519 of file klflib.cpp.

virtual bool KLFLibResourceEngine::changeEntries ( const QString subResource,
const QList< entryId > &  idlist,
const QList< int > &  properties,
const QList< QVariant > &  values 
)
pure virtualslot

Change some entries in this resource.

The entries specified by the ids idlist are modified. The properties given in properties (which should be KLFLibEntry property IDs) are to be set to the respective value in values for all the given entries in idlist. properties and values must obviously be of same size.

This function affects entries in sub-resource subResource for engines supporting feature FeatureSubResources.

A return value of TRUE indicates general success and FALSE indicates a failure.

This function should be reimplemented by subclasses to actually save the modified entries. The reimplementation should make sure that the operation is permitted (eg. by checking that canModifyData(ChangeData) is true, and should behave as described above.

Subclasses should then emit the dataChanged() signal, and return a success/failure code.

Referenced by changeEntries(), KLFLibModel::dropMimeData(), and KLFLibBrowser::slotMetaInfoChanged().

bool KLFLibResourceEngine::changeEntries ( const QList< entryId > &  idlist,
const QList< int > &  properties,
const QList< QVariant > &  values 
)
virtualslot

Change some entries in this resource.

This function is provided for convenience. The default implementation, which should largely suffice in most cases, calls the other changeEntries() function, with the default sub-resource defaultSubResource() as first argument.

Use this function for resources not supporting sub-resources (but subclasses still need to reimplement the other function, ignoring the sub-resources argument), or use this function when you explicitely want to use the default sub-resource.

Definition at line 689 of file klflib.cpp.

References changeEntries(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

bool KLFLibResourceEngine::compareDefaultSubResourceEquals ( const QString subResourceName) const
virtual

Compare our sub-resource name to another.

Returns TRUE if our default sub-resource name equals subResource, FALSE otherwise.

The default implementation tests for string equality (case sensitive). If sub-resources in the reimplemented engine are case-insensitive, then reimplement this function to compare string case-insensitive.

Reimplemented in KLFLibDBEngine.

Definition at line 509 of file klflib.cpp.

References QString::compare().

Referenced by KLFLibDefaultView::compareUrlTo().

virtual uint KLFLibResourceEngine::compareUrlTo ( const QUrl other,
uint  interestFlags = 0xfffffff 
) const
pure virtual

Compare this resource's URL with another's.

Compares the URL of this resource with other, and returns a binary OR'ed value of KlfUrlCompareFlag enum values of tests that have proved true (see KlfUrlCompareFlag for a list of URL-comparision tests in klfutil.h in klftools).

This function should return the following flag, if its corresponding tests turn out to be true. This function should NOT return any other flag that is not listed here.

  • KLFUrlComapreBaseEqual should be set if this resource shares its data with the resource given by URL other. Default sub-resources are to be ignored.

The interestFlags is a binary OR'ed value of KlfUrlCompareFlag values of tests to be performed. Any flag that is set in interestFlags indicates that the return value of this function, when binary-AND'ed with that flag, is the result (T or F) of the test the flag stands for. However, if a flag is not set in interestFlags, its state in the return value by this function is undefined.

See also klfUrlCompare().

Implemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Referenced by KLFLibDefaultView::compareUrlTo().

bool KLFLibResourceEngine::createSubResource ( const QString subResource,
const QString subResourceTitle 
)
virtualslot

Create a new sub-resource.

If they implement the feature FeatureSubResources, subclasses may reimplement this function to create a new sub-resource named subResource, with human title subResourceTitle.

subResourceTitle should be ignored for resources not implementing the FeatureSubResourceProps feature.

Returns
TRUE for success or FALSE for failure.

Subclasses should reimplement this function to provide functionality if they wish. The default implementation does nothing and returns FALSE.

Note
engines not implementing sub-resource properties should also subclass this function and not the other one, without the subResourceTitle parameter. This is because internally this function is ultimately called in all cases.

Definition at line 599 of file klflib.cpp.

Referenced by createSubResource(), KLFLibNewSubResDlg::createSubResourceIn(), KLFMainWin::loadLibrary(), and KLFLibBrowser::slotExport().

bool KLFLibResourceEngine::createSubResource ( const QString subResource)
virtualslot

Create a new sub-resource.

This function is provided for convenience. It calls

createSubResource(subResource, QString());

and returns the same result.

In other words, call this function if you don't want to provide a resource title, but subclasses should re-implement the other function to make sure full functionality is achieved (in particular also engines not implementing sub-resource properties, which will then simply ignore the title argument). This is because internally the other function is ultimately called in all cases.

Again, the default implementation of this function sould be largely sufficient in most cases and thus in principle needs not be reimplemented.

Definition at line 604 of file klflib.cpp.

References createSubResource().

void KLFLibResourceEngine::dataChanged ( const QString subResource,
int  modificationType,
const QList< KLFLib::entryId > &  entryIdList 
)
signal

Emitted when data has changed.

This signal is emitted whenever data changes in the model (eg. due to an insertEntries() function call).

The parameter subResource is the sub-resource in which the change was observed.

The parameter modificationType is the type of modification that occured. It is one of InsertData, ChangeData, DeleteData, or UnknownModification. (In particular, sub-classes should not emit other modification types). The int type is used for compatibility in Qt's SIGNAL-SLOT mechanism.

An UnknownModification change means either the library resource changed completely, or simply the backend does not wish to privide any information on which entries changed. In any case, the receiver should consider all previously read data from the resource as out of date and refresh all.

The entries that were changed are given in the argument entryIdList.

Referenced by KLFLibDBEngine::changeEntries(), KLFLibLegacyEngine::changeEntries(), KLFLibDBEngine::deleteEntries(), KLFLibLegacyEngine::deleteEntries(), KLFLibDBEngine::insertEntries(), and KLFLibLegacyEngine::insertEntries().

QString KLFLibResourceEngine::defaultSubResource ( ) const
virtual
void KLFLibResourceEngine::defaultSubResourceChanged ( const QString newDefaultSubResource)
signal

Emitted when the default sub-resource changes.

Referenced by KLFLibDBEngine::deleteSubResource(), and setDefaultSubResource().

virtual bool KLFLibResourceEngine::deleteEntries ( const QString subResource,
const QList< entryId > &  idlist 
)
pure virtualslot

Delete some entries in this resource.

The entries specified by the ids idlist are deleted.

A return value of TRUE indicates general success and FALSE indicates a failure.

This function affects entries in sub-resource subResource for engines supporting feature FeatureSubResources.

This function should be reimplemented by subclasses to actually delete the entries. The reimplementation should make sure that the operation is permitted (eg. by checking that canModifyData(DeleteData) is true, and should behave as described above.

Subclasses should then emit the dataChanged() signal, and return a success/failure code.

Referenced by deleteEntries(), KLFLibBrowser::slotCopyMoveToResource(), KLFLibBrowser::slotCut(), and KLFLibBrowser::slotDeleteSelected().

bool KLFLibResourceEngine::deleteEntries ( const QList< entryId > &  idList)
virtualslot

Delete some entries in this resource.

This function is provided for convenience. The default implementation, which should largely suffice in most cases, calls the other deleteEntries() function, with the default sub-resource defaultSubResource() as first argument.

Use this function for resources not supporting sub-resources (but subclasses still need to reimplement the other function, ignoring the sub-resources argument), or use this function when you explicitely want to use the default sub-resource.

Definition at line 696 of file klflib.cpp.

References deleteEntries(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

bool KLFLibResourceEngine::deleteSubResource ( const QString subResource)
virtualslot

Delete the given sub-resource

Returns TRUE for success and FALSE for failure.

Subclasses may reimplement this function to provide functionality. The default implementation does nothing and returns FALSE.

Subclasses should not forget to emit subResourceDeleted() after the sub-resource has been deleted (ie. upon a successful execution).

Note
Subclasses should also change the current defaultSubResource() if that is the one that was precisely deleted. Use a call to setDefaultSubResource().

Definition at line 612 of file klflib.cpp.

Referenced by KLFLibBrowser::slotExport().

virtual QList<KLFLibEntryWithId> KLFLibResourceEngine::entries ( const QString subResource,
const QList< KLFLib::entryId > &  idList,
const QList< int > &  wantedEntryProperties = QList< int >() 
)
pure virtual

query multiple entries in this resource

Returns a list of KLFLibEntryWithId s, that is a list of KLFLibEntry-ies with their corresponding IDs, exactly corresponding to the requested entries given in idList. The same order of entries in the returned list as in the specified idList is garanteed. For classes implementing sub-resources (FeatureSubResources), the sub-resource subResource is queried.

The KLFLibEntry objects are populated only of the required wantedEntryProperties, which is a list of IDs of KLFLibEntry properties (the KLFPropertizedObject-kind properties) that are set in the KLFLibEntry object. The other fields are left undefined. If the property list is empty (by default), then all properties are fetched and set.

If in the list an ID is given which does not exist in the resource, a corresponding KLFLibEntryWithId entry is returned in which the entry is set to an empty KLFLibEntry() and the id is set to -1.

If idList is empty, then this function returns an empty list.

Note
Subclasses must reimplement this function to behave as described here.

Implemented in KLFLibResourceSimpleEngine, and KLFLibDBEngine.

Referenced by KLFLibModelCache::ensureNotMinimalist(), entries(), and KLFLibModelCache::updateData().

QList< KLFLibResourceEngine::KLFLibEntryWithId > KLFLibResourceEngine::entries ( const QList< KLFLib::entryId > &  idList,
const QList< int > &  wantedEntryProperties = QList<int>() 
)
virtual

query multiple entries in this resource

Returns a list of KLFLibEntryWithId's, that is a list of KLFLibEntry-ies with their corresponding IDs, exactly corresponding to the requested entries given in idList. The same order of entries in the returned list as in the specified idList is garanteed. For classes implementing sub-resources (FeatureSubResources), the default sub-resource is queried, see setDefaultSubResource().

The KLFLibEntry objects are populated only of the required wantedEntryProperties, which is a list of IDs of KLFLibEntry properties (the KLFPropertizedObject-kind properties) that are set in the KLFLibEntry object. The other fields are left undefined. If the property list is empty (by default), then all properties are fetched and set.

If in the list an ID is given which does not exist in the resource, a corresponding KLFLibEntryWithId entry is returned in which the entry is set to an empty KLFLibEntry() and the id is set to -1.

If idList is empty, then this function returns an empty list.

The default implementation calls entries(const QString& subResource, const QList<KLFLib::entryId>& idList, const QList<int>&) with the default subresource as argument. See setDefaultSubResource().

Definition at line 629 of file klflib.cpp.

References entries(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

virtual KLFLibEntry KLFLibResourceEngine::entry ( const QString subResource,
entryId  id 
)
pure virtual

query an entry in this resource

Returns the entry (in the sub-resource subResource) corresponding to ID id, or an empty KLFLibEntry() if the id is not valid.

Note
Subclasses must reimplement this function to behave as described here.

For resources implementing FeatureSubResources, the subResource argument specifies the sub-resource in which the entry should be fetched. Classes not implementing this feature should ignore this parameter.

Implemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Referenced by entry(), and KLFLibModel::mimeData().

KLFLibEntry KLFLibResourceEngine::entry ( entryId  id)
virtual

query an entry in this resource

Returns the entry (for classes implementing the FeatureSubResources, queries the default sub-resource) corresponding to ID id, or an empty KLFLibEntry() if the id is not valid.

The default implementation calls entry(const QString& subResource, entryId id) with the default subresource as argument. See setDefaultSubResource().

Definition at line 618 of file klflib.cpp.

References entry(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

virtual bool KLFLibResourceEngine::hasEntry ( const QString subResource,
entryId  id 
)
pure virtual

query the existence of an entry in this resource

Returns TRUE if an entry with entry ID id exists in this resource, in the sub-resource subResource, or FALSE otherwise.

Note
Subclasses must reimplement this function to behave as described here.

Implemented in KLFLibResourceSimpleEngine, and KLFLibDBEngine.

Referenced by hasEntry().

bool KLFLibResourceEngine::hasEntry ( entryId  id)
virtual

query the existence of an entry in this resource

Returns TRUE if an entry with entry ID id exists in this resource or FALSE otherwise. Classes implementing the FeatureSubResources will query the default sub-resource, see setDefaultSubResource().

The default implementation calls hasEntry(const QString& subResource, entryId id) with the default subresource as argument. See setDefaultSubResource().

Definition at line 623 of file klflib.cpp.

References hasEntry(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

bool KLFLibResourceEngine::hasSubResource ( const QString subResource) const
virtual

Returns TRUE if this resource supports sub-resources and contains a sub-resource named subResource.

The default implementation checks that the FeatureSubResources is supported, and that subResourceList() contains subResource (with exact string match).

If subclasses have a more optimized method to check this, they may (but need not necessarily) reimplement this function to optimize it.

Engines that have case-insensitive resource names (eg. SQL tables) must reimplement this function to do a case-insensitive test.

Reimplemented in KLFLibDBEngine.

Definition at line 496 of file klflib.cpp.

References QStringList::contains(), FeatureSubResources, and subResourceList().

Referenced by KLFLibLegacyEngine::canDeleteSubResource(), and KLFMainWin::loadLibrary().

virtual QList<entryId> KLFLibResourceEngine::insertEntries ( const QString subResource,
const KLFLibEntryList entrylist 
)
pure virtualslot

Insert new entries in this resource.

Inserts the given library entries (given as a KLFLibEntry list) into this resource and returns a list of the IDs that were attributed to the new entries (in the same order as the given list). An individual ID of -1 means failure for that specific entry; an empty list returned means a general failure, except if entrylist is empty.

The entries are inserted into sub-resource subResource, if sub-resources are supported (FeatureSubResources). Otherwise the subResource parameter should be ignored by subclasses.

This function should be reimplemented by subclasses to actually save the new entries. The reimplementation should make sure that the operation is permitted (eg. by checking that canModifyData(InsertData) is true, and should behave as described above.

Subclasses should then emit the dataChanged() signal, and return a success/failure code.

Referenced by KLFLibModel::dropMimeData(), insertEntries(), insertEntry(), KLFMainWin::loadLibrary(), KLFLibBrowser::slotCopyMoveToResource(), KLFLibBrowser::slotExport(), KLFLibBrowser::slotExportSelection(), KLFLibBrowser::slotMetaInfoChanged(), and KLFLibBrowser::slotPaste().

QList< KLFLibResourceEngine::entryId > KLFLibResourceEngine::insertEntries ( const KLFLibEntryList entrylist)
virtualslot

Insert new entries in this resource.

This function is provided for convenience. Inserts the entries entrylist into this resource.

Use this function for resources not supporting sub-resources (but subclasses still need to reimplement the other function, ignoring the sub-resources argument), or use this function when you explicitely want to use the default sub-resource.

A reasonable default implementation is provided. Subclasses are not required to reimplement this function.

Definition at line 683 of file klflib.cpp.

References insertEntries(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

KLFLibResourceEngine::entryId KLFLibResourceEngine::insertEntry ( const QString subResource,
const KLFLibEntry entry 
)
virtualslot

Insert an entry into this resource.

This function is provided for convenience. Inserts the entry entry into the subresource subResource of this resource. Resources not implementing the sub-resources feature (FeatureSubResources) should ignore the subResource parameter.

API users should use the version of insertEntry(const KLFLibEntry& entry) when dealing with resources that do not implement the FeatureSubResources feature.

This function is already implemented as shortcut for calling the list version. Subclasses need in principle NOT reimplement this function.

Definition at line 669 of file klflib.cpp.

References insertEntries(), and QList::size().

Referenced by insertEntry(), and KLFMainWin::slotEvaluate().

KLFLibResourceEngine::entryId KLFLibResourceEngine::insertEntry ( const KLFLibEntry entry)
virtualslot

Insert an entry into this resource.

This function is provided for convenience. Inserts the entry entry into this resource.

Use this function for resources not supporting sub-resources (but subclasses still need to reimplement the other function, ignoring the sub-resources argument), or use this function when you explicitely want to use the default sub-resource.

A reasonable default implementation is provided. Subclasses are not required to reimplement this function.

Definition at line 678 of file klflib.cpp.

References insertEntry(), and KLFLIBRESOURCEENGINE_WARN_NO_DEFAULT_SUBRESOURCE.

virtual bool KLFLibResourceEngine::isReadOnly ( ) const
inlinevirtual

query read-only state

See Class Documentation for more details.

Definition at line 595 of file klflib.h.

Referenced by baseCanModifyStatus(), KLFLibLegacyEngine::save(), and KLFMainWin::slotEvaluate().

bool KLFLibResourceEngine::loadResourceProperty ( const QString propName,
const QVariant value 
)
virtualslot

Set the given property to the given value.

Very similar to calling setResourceProperty() with the respective property ID (see KLFPropertizedObject::propertyIdForName()), except the property is registered if it does't exist.

The property is registered if it doesn't exist yet and the canRegisterProperty() returns TRUE.

Once the property has been possibly registered, setResourceProperty() is called.

Definition at line 716 of file klflib.cpp.

References canRegisterProperty(), KLFPropertizedObject::propertyIdForName(), KLFPropertizedObject::registerProperty(), and setResourceProperty().

virtual bool KLFLibResourceEngine::locked ( ) const
inlinevirtual

Is this resource is locked?

If the resource is locked (property PropLocked), no changes can be in principle made, except setLocked(false) (of course...).

Note: the subclass is responsible to check in functions such as insertEntry(), that the resource is not locked and not read-only etc. (checked all-in-one with canModifyData()).

The default implementation has some limited support for the locked property: see setLocked().

Definition at line 610 of file klflib.h.

References KLFPropertizedObject::property(), and QVariant::toBool().

Referenced by KLFLibResPropEditor::apply(), baseCanModifyStatus(), KLFMainWin::slotEvaluate(), and KLFLibResPropEditor::updateResourceProperties().

void KLFLibResourceEngine::operationStartReportingProgress ( KLFProgressReporter progressReporter,
const QString descriptiveText 
)
signal

Emitted at the beginning of a long operation during which progress will be reported by emission of KLFProgressReporter::progress() of the given object progressReporter.

Parameters
progressReporteris the object that will emit its progress() at regular intervals to inform caller of operation progress.
descriptiveTextis some text describing the nature of the operation in progress

Subclasses have to use KLFProgressReporter directly. It's very simple to use, example:

int do_some_long_computations(...) {
int num_of_steps = ... ;
KLFProgressReporter progressReporter(0, num_of_steps, this);
// ...
int current_step = 0;
for ( ... many iterations ... ) {
progressReporter.doReportProgress(current_step++);
.... // perform a long computation iteration
}
// finally emit the last progress value
progressReporter.doReportProgress(num_of_steps);
...
return some_result;
}

The signal operationStartReportingProgress() is suitable to use in conjunction with a KLFProgressDialog.

Referenced by KLFLibDBEngine::allEntries(), KLFLibDBEngine::changeEntries(), KLFLibDBEngine::deleteEntries(), KLFLibDBEngine::entries(), KLFLibDBEngine::insertEntries(), and KLFLibDBEngine::query().

virtual int KLFLibResourceEngine::query ( const QString subResource,
const Query query,
QueryResult result 
)
pure virtual

query entries in this resource with specified property values

Returns a list of all entries in this resource (and in sub-resource subResource for the engines supporting this feature) that match all the required matches specifed in matchcondition.

Note
the subclass is responsible for providing a functional implementation of this function. Subclasses that don't want to pass much time to implement this feature can resort to calling the static method KLFLibResourceSimpleEngine::queryImpl() that provides a functional (but not very optimized) default implementation; the KLFLibResourceSimpleEngine::testMatchConditionImpl() function may prove useful for testing match conditions; and the utilities KLFLibEntrySorter and KLFLibResourceSimpleEngine::QueryResultListSorter might prove useful for sorting entries in conjuction with qLowerBound().

query is a Query object that describes the query. See Query for details.

result is a QueryResult structure that will be filled with the queried data. See QueryResult for details.

The matches are returned in the following way into the result structure:

  • if the appropriate flag in result is set, then result.entryIdList is set to a list of all entry IDs that matched
  • if the appropriate flag in result is set, then result.rawEntryList is set to a list of all entries that matched, stored as KLFLibEntry objects. Only the requested properties are populated (specified by query.wantedEntryProperties)
  • if the appropriate flag in result is set, then result.entryWithIdList is set to a list of all entries, with their corresponding entry ID, that matched (similar to the return value of allEntries()). Only the requested properties are populated (as specified by result.wantedEntryProperties.)

If the orderPropId member in query is not -1, then the returned results (in all to-be-filled lists) are ordered according to the entry property ID orderPropId, in the order specified by orderDirection.

Returns
the number of items in the resource that matched. If a limit was set in query, then at most that many results are returned. 0 is returned if no match was found. -1 can be returned to signify an error (eg. invalid regexp, i/o error, etc.).

The KLFLibEntry objects are populated only of the required wantedEntryProperties as set in query (see Query), which is a list of IDs of KLFLibEntry properties (the KLFPropertizedObject-kind properties) that are set in the KLFLibEntry object. If the property list is empty (by default), then all properties are fetched and set. Note that if this list is not empty, then the properties not in the list are undefined: they may be uninitialized, set to null/invalid, or filled eg. by an implementation that ignores wantedEntryProperties.

Note
it is possible to specify a property ID in the match condition that isn't given in wantedEntryProperties, and reimplementations must handle this. Reason: even if this may seem inconsistent, it can be easily implemented in some examples of engines (SQL condition, ...) and can easily be worked around in other engines by adding the requested property to the wanted property list. Example: listing entries by date/time order, without necessarily displaying the date/time.

Implemented in KLFLibResourceSimpleEngine, and KLFLibDBEngine.

Referenced by KLFLibModelCache::fetchMore(), KLFLibModelCache::rebuildCache(), and KLFMainWin::slotEvaluate().

virtual QList<QVariant> KLFLibResourceEngine::queryValues ( const QString subResource,
int  entryPropId 
)
pure virtual

List all distinct values that a property takes in all entries.

Returns
A list of all (distinct) values that a given property in all the entries of sub-resource subResource takes.

For example, KLFLibModel uses this function in category tree mode to get the category tree, by passing KLFLibEntry::Category as entryPropId.

The order of the elements within the returned list is not defined.

In mathematical terms, if $f_{pid}(entry)$ is the value of property ID pid of the entry entry, then this function returns the range (=set of all reached values) of $f_{pid}$.

KLFLibResourceSimpleEngine::queryValuesImpl() offers a very simple non-optimized implementation of this function that you can use in your resource engine subclass if you don't want to do this yourself. That function is automatically re-implemented if you subclass KLFLibResourceSimpleEngine.

Implemented in KLFLibResourceSimpleEngine, and KLFLibDBEngine.

Referenced by KLFLibModelCache::rebuildCache().

bool KLFLibResourceEngine::renameSubResource ( const QString oldSubResourceName,
const QString newSubResourceName 
)
virtualslot

Rename the sub-resource oldSubResourceName to newSubResourceName.

Note
we are talking about the resource name (eg. the table name in the database), not the title (stored as a sub-resource property, for engines supporting FeatureSubResourceProps).

Returns TRUE for success and FALSE for failure.

Subclasses may reimplement this function to provide functionality. The default implementation does nothing and returns FALSE.

Subclasses should not forget to emit subResourceRenamed() after a successful sub-resource rename.

Note
Subclasses should also adjust the current defaultSubResource() if that is the one that was precisely renamed. Use a call to setDefaultSubResource().

Definition at line 608 of file klflib.cpp.

QVariant KLFLibResourceEngine::resourceProperty ( const QString name) const
virtual

Get the value of a resource property.

Returns the value of the given resource property. If the property is not registered, returns an invalid QVariant with a warning.

For built-in resource properties, consider using the simpler locked(), title() and viewType() methods (for example).

Definition at line 711 of file klflib.cpp.

References KLFPropertizedObject::property().

Referenced by KLFLibResPropEditor::updateResourceProperties().

void KLFLibResourceEngine::resourcePropertyChanged ( int  propId)
signal

Emitted when a resource property changes.

Parameters
propIdthe ID of the property that changed.

Referenced by setResourceProperty(), and KLFLibLegacyEngine::updateResourceProperty().

virtual bool KLFLibResourceEngine::saveResourceProperty ( int  propId,
const QVariant value 
)
protectedpure virtual

Save a resource property to the backend resource data.

Subclasses should reimplement this function to save the value of the given resource property to the knew given value.

If the new value is inacceptable, or if the operation is not permitted, the subclass should return FALSE, in which case the resource property will not be changed.

Implemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Referenced by setResourceProperty().

bool KLFLibResourceEngine::saveTo ( const QUrl newPath)
virtualslot

If the FeatureSaveTo is supported (passed to the constructor), reimplement this function to save the resource data in the new path specified by newPath.

The newPath must be garanteed to have same schema as the previous url.

Bug:
........ THIS FUNCTION IS NOT COMPLETELY SUPPORTED IN KLFLibBrowser. ....... It also needs a "concept clarification", ie. what this is supposed to do exactly and how it is supposed to be used.

Definition at line 704 of file klflib.cpp.

void KLFLibResourceEngine::setDefaultSubResource ( const QString subResource)
virtualslot

Set the default sub-resource.

When calling the variants of insertEntry(), changeEntry(), etc. that do not take a sub-resource argument, and when this resource implements FeatureSubResources, then calls to those functions will access the default sub-resource, which can be set with this function.

This function should be used only with subclasses implementing FeatureSubResources.

The default implementation remembers subResource to be the new defaultSubResource() and emits defaultSubResourceChanged(). It does nothing if subResource is already the default sub-resource.

Warning
Reimplementing this function has a drawback: it will not be called with the argument given in the constructor (impossible to call reimplemented virtual methods in base constructor). Instead, the sub-class has to explicitely call its own implementation in its own constructor to ensure full proper initialization.

Definition at line 584 of file klflib.cpp.

References defaultSubResourceChanged().

Referenced by KLFLibResPropEditor::apply(), and KLFLibDBEngine::deleteSubResource().

bool KLFLibResourceEngine::setLocked ( bool  locked)
virtualslot

Set the resource to be locked.

See locked() for more doc.

If the feature flags do not contain FeatureLocked, then this function returns immediately FALSE. Otherwise, this function calls setResourceProperty() with arguments PropLocked and the new value.

The default implementation should suffice; subclass saveResourceProperty() for actually saving the new value into the resource backend data, and for more control over setting properties, or possibly subclass setResourceProperty() for even more control.

Definition at line 559 of file klflib.cpp.

References FeatureLocked, PropLocked, and setResourceProperty().

Referenced by KLFLibResPropEditor::apply(), and KLFMainWin::slotEvaluate().

bool KLFLibResourceEngine::setReadOnly ( bool  readonly)
virtualslot

Set the resource to be read-only or not.

If the FeatureReadOnly was given to the constructor, The base implementation sets the read-only flag to readonly (this is then returned by isReadOnly()). The base implementation does nothing and returns FALSE if the feature FeatureReadOnly is not supported.

Definition at line 574 of file klflib.cpp.

References FeatureReadOnly.

bool KLFLibResourceEngine::setResourceProperty ( int  propId,
const QVariant value 
)
virtualslot

Set a resource property to the given value.

This function calls in turn:

Note
This function fails immediately if propId is not a valid registered property ID, or if canModifyProp() returns FALSE.

Definition at line 731 of file klflib.cpp.

References canModifyProp(), KLFPropertizedObject::propertyIdRegistered(), resourcePropertyChanged(), saveResourceProperty(), and KLFPropertizedObject::setProperty().

Referenced by KLFLibResPropEditor::advPropEdited(), loadResourceProperty(), setLocked(), setTitle(), and setViewType().

bool KLFLibResourceEngine::setSubResourceProperty ( const QString subResource,
int  propId,
const QVariant value 
)
virtualslot

Sets the given sub-resource property of sub-resource subResource to the value value, if the operation is possible and legal.

Returns
TRUE for success, FALSE for failure.

The default implementation does nothing and returns FALSE.

Definition at line 593 of file klflib.cpp.

Referenced by KLFLibResPropEditor::advSubResPropEdited(), KLFLibResPropEditor::apply(), KLFMainWin::loadLibrary(), KLFLibBrowserViewContainer::openView(), KLFMainWin::slotEvaluate(), KLFLibBrowser::slotExport(), and KLFLibBrowser::slotResourceRenameFinished().

bool KLFLibResourceEngine::setTitle ( const QString title)
virtualslot

set a new resource title for this library resource

Stores the new resource title. The title is a human string to display eg. in the tabs of the KLFLibBrowser library browser. [KLFLibBrowser: see klfapp library]

This function calls directly setResourceProperty().

The default implementation should suffice; subclass saveResourceProperty() for actually saving the new value into the resource backend data, and for more control over setting properties, or possibly subclass setResourceProperty() for even more control.

Definition at line 555 of file klflib.cpp.

References PropTitle, and setResourceProperty().

Referenced by KLFLibResPropEditor::apply(), KLFMainWin::loadLibrary(), KLFLibBrowser::slotExport(), and KLFLibBrowser::slotResourceRenameFinished().

bool KLFLibResourceEngine::setViewType ( const QString viewType)
virtualslot

Store the given view type in the ViewType property.

Calls directly setResourceProperty().

The default implementation should suffice; subclass saveResourceProperty() for actually saving the new value into the resource backend data, and for more control over setting properties, or possibly subclass setResourceProperty() for even more control.

Definition at line 569 of file klflib.cpp.

References PropViewType, and setResourceProperty().

Referenced by KLFMainWin::loadLibrary(), KLFLibBrowser::openResource(), and KLFLibBrowserViewContainer::openView().

void KLFLibResourceEngine::subResourceCreated ( const QString newSubResource)
signal

Emitted when a sub-resource is created.

This signal should be emitted by engines supporting feature FeatureSubResources, at the end of a (successful) createSubResource() call.\

Referenced by KLFLibDBEngine::createSubResource(), and KLFLibLegacyEngine::createSubResource().

void KLFLibResourceEngine::subResourceDeleted ( const QString subResource)
signal

Emitted when a sub-resource is deleted.

This signal should be emitted by engines supporting feature FeatureSubResources, at the end of a (successful) deleteSubResource() call.

Referenced by KLFLibDBEngine::deleteSubResource(), and KLFLibLegacyEngine::deleteSubResource().

virtual QStringList KLFLibResourceEngine::subResourceList ( ) const
inlinevirtual

Returns a list of sub-resources in this resource. This function is relevant only if the FeatureSubResources is implemented.

Reimplemented in KLFLibLegacyEngine, and KLFLibDBEngine.

Definition at line 722 of file klflib.h.

Referenced by hasSubResource(), KLFLibEngineFactory::listSubResourcesWithTitles(), KLFMainWin::loadLibrary(), KLFLibBrowserViewContainer::openSubResourceActions(), and KLFLibResPropEditor::updateSubResources().

QVariant KLFLibResourceEngine::subResourceProperty ( const QString subResource,
int  propId 
) const
virtual
void KLFLibResourceEngine::subResourcePropertyChanged ( const QString subResource,
int  propId 
)
signal

Emitted when a sub-resource property changes.

This signal should only be emitted by engines supporting feature FeatureSubResourceProps as well as FeatureSubResources.

Parameters
subResourcethe affected sub-resource name
propIdthe ID of the property that changed
virtual QList<int> KLFLibResourceEngine::subResourcePropertyIdList ( ) const
inlinevirtual

Returns a list of sub-resource properties that are supported by this resource.

This function makes sense to be reimplemented and called only if this resource supports features FeatureSubResources and FeatureSubResourceProps.

The default implementation returns an empty list.

Reimplemented in KLFLibDBEngine.

Definition at line 780 of file klflib.h.

Referenced by KLFLibResPropEditor::updateSubResourceProperties().

QString KLFLibResourceEngine::subResourcePropertyName ( int  propId) const
virtual

Returns a property name for the sub-resource property propId.

The name should be significant but machine-compatible (in particular, NOT translated) as it could be used to identify the property for example to save it possibly...

the default implementation returns reasonable names for SubResPropTitle, SubResPropLocked, and SubResPropViewType, and returns the propId in a string for other IDs (QString::number()).

This function makes sense to be called only for engines supporting FeatureSubResourceProps.

Definition at line 533 of file klflib.cpp.

References QString::number(), SubResPropLocked, SubResPropTitle, and SubResPropViewType.

Referenced by KLFLibResPropEditor::updateSubResourceProperties().

void KLFLibResourceEngine::subResourceRenamed ( const QString oldSubResourceName,
const QString newSubResourceName 
)
signal

Emitted when a sub-resource is renamed.

This signal should be emitted by engines supporting feature FeatureSubResources, at the end of a (successful) renameSubResource() call.\

Referenced by KLFLibLegacyEngine::renameSubResource().

virtual QString KLFLibResourceEngine::suggestedViewTypeIdentifier ( ) const
inlinevirtual

Suggested library view widget to view this resource with optimal user experience :-) . Return QString() for default view.

Definition at line 704 of file klflib.h.

Referenced by KLFLibBrowser::openResource().

virtual uint KLFLibResourceEngine::supportedFeatureFlags ( ) const
inlinevirtual

List of features supported by this resource engine.

Use this function to probe whether this resource instance supports a specific feature. For example a property editor widget might want to know if this resource supportes the FeatureLocked feature, to enable or disable the corresponding check box.

Do not reimplement in subclasses, simply pass the feature flags to the constructor.

Definition at line 550 of file klflib.h.

Referenced by KLFLibResPropEditor::apply(), KLFLibDefaultView::compareUrlTo(), KLFLibNewSubResDlg::createSubResourceIn(), KLFLibBrowser::displayTitle(), KLFLibNewSubResDlg::KLFLibNewSubResDlg(), KLFLibResPropEditor::KLFLibResPropEditor(), KLFLibEngineFactory::listSubResourcesWithTitles(), KLFMainWin::loadLibrary(), KLFLibBrowser::openResource(), KLFLibBrowserViewContainer::openSubResourceActions(), KLFLibBrowserViewContainer::openView(), KLFMainWin::slotEvaluate(), KLFLibBrowser::slotExport(), KLFLibBrowser::slotRefreshResourceActionsEnabled(), KLFLibBrowser::slotResourceRename(), and KLFLibModel::url().

bool KLFLibResourceEngine::thisOperationProgressBlocked ( ) const
protected
virtual QString KLFLibResourceEngine::title ( ) const
inlinevirtual
QUrl KLFLibResourceEngine::url ( uint  flags = 0x0) const
virtual

query URL

Returns the identifying URL of this resource.

Note
This is not quite the URL passed to the constructor. Some query items are recognized and stripped. See the Class Documentation for more information.

Flags may be specified as to which query items we would like to add to URL (eg. default sub-resource, read-only status). see WantUrlFormatFlag.

See also KLFAbstractLibView::url(). That function gives also information on what part of the resource it displays.

Definition at line 457 of file klflib.cpp.

References QUrl::addQueryItem(), FeatureSubResources, QString::isNull(), WantUrlDefaultSubResource, and WantUrlReadOnly.

Referenced by KLFLibDBEngine::compareUrlTo(), KLFLibLegacyEngine::compareUrlTo(), KLFLibLegacyEngine::createDotKLF(), KLFLibDBEngine::createSqlite(), KLFLibNewSubResDlg::createSubResourceIn(), KLFLibBrowser::openResource(), KLFLibBrowserViewContainer::openSubResourceActions(), KLFLibDBEngine::openUrl(), KLFLibBrowserViewContainer::openView(), KLFLibLegacyEngine::save(), KLFLibDBEngine::saveTo(), KLFLibBrowser::slotExport(), KLFLibBrowser::slotResourceNewSubRes(), KLFLibBrowser::slotUpdateForResourceProperty(), KLFLibResPropEditor::updateResourceProperties(), and KLFLibModel::url().

virtual QString KLFLibResourceEngine::viewType ( ) const
inlinevirtual

The (last) View Type used to display this resource.

Definition at line 613 of file klflib.h.

References KLFPropertizedObject::property(), and QVariant::toString().

Referenced by KLFLibBrowser::openResource().


The documentation for this class was generated from the following files:

Generated by doxygen 1.8.6