A simple class to access/declare resources (not thread-safe) More...
Public Member Functions | |
| SimpleResourcesUser () | |
| Constructor. More... | |
| SimpleResourcesUser (const SimpleResourcesUser &other) | |
| Copy constructor. More... | |
| virtual | ~SimpleResourcesUser () |
| Constructor. More... | |
| template<class T > | |
| void | declareResource (QString name, T *resource) |
| Declares the name for a resource. More... | |
| void | deleteResource (QString name) |
| Deletes the resource with the specified name. More... | |
| template<class T > | |
| T * | getResource (QString name) |
| Returns a pointer to the resource declared with the specified name. More... | |
| bool | hasResource (QString name) const |
| Returns true if a resource with name specified has been declared. More... | |
| SimpleResourcesUser & | operator= (const SimpleResourcesUser &other) |
| Copy operator. More... | |
| virtual void | shareResourcesWith (ResourcesUser *other) |
| The function to share resources. More... | |
 Public Member Functions inherited from Resource | |
| virtual | ~Resource () |
| Destructor. More... | |
Protected Member Functions | |
| template<class T > | |
| T * | getResource () |
| Returns a pointer to the resource whose change we have been notified of. More... | |
| virtual void | resourceChanged (QString name, ResourceChangeType changeType) |
| The function called when a resource you use is changed. More... | |
| Protected Member Functions inherited from ResourcesUser | |
| ResourcesUser () | |
| Constructor. More... | |
| ResourcesUser (const ResourcesUser &other) throw () | |
| Copy constructor. More... | |
| virtual | ~ResourcesUser () |
| Constructor. More... | |
| ResourcesUser & | operator= (const ResourcesUser &other) throw () |
| Copy operator. More... | |
Additional Inherited Members | |
| Public Types inherited from ResourcesUser | |
| typedef Resource::ResourceChangeType | ResourceChangeType |
| The change that happened to a resource. More... | |
| Public Types inherited from Resource | |
| enum | ResourceChangeType { Created, Modified, Deleted } |
| The change that happened to a resource. More... | |
| Protected Attributes inherited from ResourcesUser | |
| ResourceCollectionHolder | m_resources |
| The object holding the shared resources. More... | |
Detailed Description
A simple class to access/declare resources (not thread-safe)
A resource is a pointer to a variable of a primitive type or to an object that is associated to a resource name. The resource name is a string that can be used to access the resource. If you want an instance of a class to be used as a resource the class must be a subclass (direct or indirect) of one of the following classes:
- Resource
- ParameterSettable
- QObject
When you declare a resource, you give it a name and specify the pointer to an object/variable of a primitive type, using the declareResource() function. When you need to get the resource (i.e the pointer), you can access it calling the getResource() method and passing the resource name. Once you declare a resource, you can change the pointer over time, simply re-declaring a resource with the same resource name. An instance of this class does never frees memory for the resource, so this must be managed outside (e.g. by the actual owner of the resource). Accessing resources using this class is not thread-safe. To actually get the resource you can use the getResource() function. If you instead want to delete a resource, use deleteResource().
Using a single instance of this class is not very useful. The purpouse of the resource mechanism is to allow objects to declare certain resources at runtime and then let other objects use it without the need to know who is the owner of the resource. To be able to do this you have to associate different instances of this class creating a groups of interconnected ResourcesUser objects sharing the same set of resources. Each instance can then declare resources or use a subset of them. To be able to do this you have to use the shareResourcesWith() function. This function takes a pointer to another ResourcesUser class with which resources will be shared. Be aware that when you call shareResourcesWith() all resources declared by the calling instance of ResourcesUser will be lost, that is they will no longer be accessible by that object (as stated above, their memory will not be freed in any case). After the call to shareResourcesWith() the calling object will share all resources with the other ResourcesUser object. The sharing of resources is "transitive", that is if you call shareResourcesWith() to associate object A with another ResourcesUser object B that is already associated with a third object C, then A, B and C will all share the same resource set. So, for example, if you want a certain number of objects to share resources among them you can simply call the shareResourcesWith() function of all of them passing always the same object as parameter. You can call shareResourcesWith() with a NULL parameter to remove the association of the ResourcesUser instance with other instances. Note that the shareResourcesWith() function is NOT thread safe.
You can be notified when a certain resource changes (i.e. when declareResource() or deleteResource() is called for that resource) using the function observeResourceChange() and passing the name of the resource you want to observe for changes. From then on, when the resource changes the resourceChanged() function is called (the default implementation does nothing). You can pass to observeResourceChange a non-existing resource. In this case you will be notified when the resource gets created. To stop being notified for resource changes use stopObservingResourceChange(). An important notice about changing a resource: it is possible that objects using a given resource keep a pointer to it because they need to so some cleanup with the old resource before start using the new one. Because of this it is important that when you re-declare a resource, you first call declareResource() with the new istance of the resource and then delete the old one.
- Note
- A convenient way of using this class is to have your classes that need to access resources inherit from this one, as in the example above.
- Accesing resources using this class is not thread-safe, no lock is acquired. Because of this be careful if you share resources with ConcurrentResourcesUser instances (which are instead thread-safe)
- Most functions in this class are not exception safe...
Definition at line 227 of file resourcesuser.h.
Constructor & Destructor Documentation
Constructor.
Definition at line 86 of file resourcesuser.cpp.
| SimpleResourcesUser | ( | const SimpleResourcesUser & | other | ) |
Copy constructor.
This object and the one from which it is copied will share the same resources (no need to call shareResourcesWith()). This object will also receive notifications for the same resources
- Parameters
-
other the object to copy
Definition at line 94 of file resourcesuser.cpp.
|
virtual |
Constructor.
Definition at line 133 of file resourcesuser.cpp.
Member Function Documentation
|
inline |
Declares the name for a resource.
This method overwrites any previous declaration with the same name.
- Parameters
-
name the name of the resource to declare resource the pointer to the object/variable resource
Definition at line 281 of file resourcesuser.h.
References ResourceHandler::set().
| void deleteResource | ( | QString | name | ) |
Deletes the resource with the specified name.
- Parameters
-
name the name of the resource to delete
- Warning
- it will raise an exception if the resource doesn't exist
Definition at line 147 of file resourcesuser.cpp.
References ResourceHandler::exists(), ResourceCollection::getResource(), ResourcesUser::m_resources, and ResourceHandler::unset().
|
inline |
Returns a pointer to the resource declared with the specified name.
- Parameters
-
name the name of the resource to return.
- Returns
- the pointer to the resource if it exists
- Warning
- it will raise an exception if the type does not correspond to what requested or the resource doesn't exist
Definition at line 302 of file resourcesuser.h.
References ResourceHandler::exists(), and ResourceHandler::get().
|
inlineprotected |
Returns a pointer to the resource whose change we have been notified of.
You can use this function only inside a call to resourceChanged (as a shortcut to get the resource being notified). This is why it is protected.
- Returns
- the pointer to the resource or NULL if we are not inside a call to resourceChanged()
- Warning
- it will raise an exception if the type does not correspond to what requested
Definition at line 366 of file resourcesuser.h.
|
inline |
Returns true if a resource with name specified has been declared.
- Parameters
-
name the name of the resource
- Returns
- true if the resource exists; false otherwise
Definition at line 334 of file resourcesuser.h.
| SimpleResourcesUser & operator= | ( | const SimpleResourcesUser & | other | ) |
Copy operator.
This object and the one from which it is copied will share the same resources (no need to call shareResourcesWith()). This object will also receive notifications for the same resources
- Parameters
-
other the object to copy
Definition at line 107 of file resourcesuser.cpp.
References ResourcesUser::operator=().
|
protectedvirtual |
The function called when a resource you use is changed.
The default implementation does nothing
- Parameters
-
name the name of the resource that has changed. chageType the type of change the resource has gone through (whether it was created, modified or deleted)
- Note
- This function is called from the thread in which the resource has changed
Definition at line 160 of file resourcesuser.cpp.
|
virtual |
The function to share resources.
The calling instance will lose the possibility to access the resources it had before this call
- Parameters
-
other the instance with which resources will be shared. If NULL we lose the association with other objects and start with an empty resource set
- Note
- This is NOT thread safe (both this and the other instance should not be being accessed by other threads)
Reimplemented from ResourcesUser.
Definition at line 138 of file resourcesuser.cpp.
References ResourcesUser::shareResourcesWith().
The documentation for this class was generated from the following files:
- configuration/include/resourcesuser.h
- configuration/src/resourcesuser.cpp