ctk_qt5.7.1_x86_vs2015.zip

/*============================================================================= Library: CTK Copyright (c) German Cancer Research Center, Division of Medical and Biological Informatics Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. =============================================================================*/ #ifndef CTKPLUGINCONTEXT_H_ #define CTKPLUGINCONTEXT_H_ #include <QHash> #include <QString> #include <QVariant> #include <QUrl> #include <QSharedPointer> #include <QFileInfo> #include "ctkPluginFramework_global.h" #include "ctkPluginEvent.h" #include "ctkServiceException.h" #include "ctkServiceReference.h" #include "ctkServiceRegistration.h" #include "ctkPluginFrameworkExport.h" // CTK class forward declarations class ctkPlugin; class ctkPluginPrivate; class ctkPluginContextPrivate; /** * \ingroup PluginFramework * * A plugin's execution context within the Framework. The context is used to * grant access to other methods so that this plugin can interact with the * Framework. * * <p> * <code>ctkPluginContext</code> methods allow a plugin to: * <ul> * <li>Subscribe to events published by the Framework. * <li>Register service objects with the Framework service registry. * <li>Retrieve <code>ServiceReferences</code> from the Framework service * registry. * <li>Get and release service objects for a referenced service. * <li>Install new plugins in the Framework. * <li>Get the list of plugins installed in the Framework. * <li>Get the {@link ctkPlugin} object for a plugin. * <li>Create <code>QFile</code> objects for files in a persistent storage * area provided for the plugin by the Framework. * </ul> * * <p> * A <code>ctkPluginContext</code> object will be created and provided to the * plugin associated with this context when it is started using the * {@link ctkPluginActivator::start} method. The same <code>ctkPluginContext</code> * object will be passed to the plugin associated with this context when it is * stopped using the {@link ctkPluginActivator::stop} method. A * <code>ctkPluginContext</code> object is generally for the private use of its * associated plugin and is not meant to be shared with other plugins in the * plugin environment. * * <p> * The <code>ctkPlugin</code> object associated with a <code>ctkPluginContext</code> * object is called the <em>context plugin</em>. * * <p> * The <code>ctkPluginContext</code> object is only valid during the execution of * its context plugin; that is, during the period from when the context plugin * is in the <code>STARTING</code>, <code>STOPPING</code>, and * <code>ACTIVE</code> plugin states. If the <code>ctkPluginContext</code> * object is used subsequently, a <code>ctkIllegalStateException</code> must be * thrown. The <code>ctkPluginContext</code> object must never be reused after * its context plugin is stopped. * * <p> * The Framework is the only entity that can create <code>ctkPluginContext</code> * objects and they are only valid within the Framework that created them. * * @remarks This class is thread safe. */ class CTK_PLUGINFW_EXPORT ctkPluginContext { public: ~ctkPluginContext(); /** * Returns the value of the specified property. If the key is not found in * the Framework properties, the system properties are then searched. The * method returns an invalid QVariant if the property is not found. * * @param key The name of the requested property. * @return The value of the requested property, or an invalid QVariant if * the property is undefined. */ QVariant getProperty(const QString& key) const; /** * Returns the <code>ctkPlugin</code> object associated with this * <code>ctkPluginContext</code>. This plugin is called the context plugin. * * @return The <code>ctkPlugin</code> object associated with this * <code>ctkPluginContext</code>. * @throws ctkIllegalStateException If this ctkPluginContext is no * longer valid. */ QSharedPointer<ctkPlugin> getPlugin() const; /** * Returns the plugin with the specified identifier. * * @param id The identifier of the plugin to retrieve. * @return A <code>ctkPlugin</code> object or <code>0</code> if the * identifier does not match any installed plugin. */ QSharedPointer<ctkPlugin> getPlugin(long id) const; /** * Returns a list of all installed plugins. * <p> * This method returns a list of all plugins installed in the plugin * environment at the time of the call to this method. However, since the * Framework is a very dynamic environment, plugins can be installed or * uninstalled at anytime. * * @return A QList of <code>ctkPlugin</code> objects, one object per * installed plugin. */ QList<QSharedPointer<ctkPlugin> > getPlugins() const; /** * Registers the specified service object with the specified properties * under the specified class names into the Framework. A * <code>ctkServiceRegistration</code> object is returned. The * <code>ctkServiceRegistration</code> object is for the private use of the * plugin registering the service and should not be shared with other * plugins. The registering plugin is defined to be the context plugin. * Other plugins can locate the service by using either the * {@link #getServiceReferences} or {@link #getServiceReference} method. * * <p> * A plugin can register a service object that implements the * {@link ctkServiceFactory} interface to have more flexibility in providing * service objects to other plugins. * * <p> * The following steps are required to register a service: * <ol> * <li>If <code>service</code> is not a <code>ctkServiceFactory</code>, an * <code>ctkInvalidArgumentException</code> is thrown if <code>service</code> * is not an instance of all the specified class names. * <li>The Framework adds the following service properties to the service * properties from the specified <code>ctkDictionary</code> (which may be * omitted): <br/> * A property named {@link ctkPluginConstants#SERVICE_ID} identifying the * registration number of the service <br/> * A property named {@link ctkPluginConstants#OBJECTCLASS} containing all the * specified classes. <br/> * Properties with these names in the specified <code>ctkDictionary</code> will * be ignored. * <li>The service is added to the Framework service registry and may now be * used by other plugins. * <li>A service event of type {@link ctkServiceEvent#REGISTERED} is fired. * <li>A <code>ctkServiceRegistration</code> object for this registration is * returned. * </ol> * * @param clazzes The class names under which the service can be located. * The class names will be stored in the service's * properties under the key {@link ctkPluginConstants#OBJECTCLASS}. * @param service The service object or a <code>ctkServiceFactory</code> * object. * @param properties The properties for this service. The keys in the * properties object must all be <code>QString</code> objects. See * {@link ctkPluginConstants} for a list of standard service property keys. * Changes should not be made to this object after calling this * method. To update the service's properties the * {@link ctkServiceRegistration::setProperties} method must be called. * The set of properties may be omitted if