View source for Events:CTK-Hackfest-2010/SlicerQtPluginArchitecture

= Goal =
* Provide a cross-platform plugin architecture
* Modular and extensible

= Big picture =
* a Factory manages a collection of Factory items
* Factory Item provides load() and instanciate() methods
* Factory provided registerItems() and load(key) methods 

= Under the hood =

* The Qt layer
** QPlugin (from Qt docmentation ... )
*** QPluginLoader checks that a plugin is linked against the same version of Qt as the application.
*** QPluginLoader provides direct access to a root component object (instance()), instead of forcing you to resolve a C function manually. 
*** In order to speed up loading and validation of plugins, some of the information that is collected during loading is cached in persistent memory (through QSettings).
** QLibrary
** QObject / Object

* The CTK layer
** Base class: qCTKAbstractFactory
<pre>
template<typename BaseClassType>
class qCTKAbstractFactory
{
  ...
public:
  explicit qCTKAbstractFactory();
  virtual ~qCTKAbstractFactory();
  virtual void printAdditionalInfo();

  /// Return factory name
  virtual QString name()const = 0;

  /// Create an instance of the object
  virtual BaseClassType * instantiate(const QString& itemKey);

  /// Uninstanciate the object
  void uninstantiate(const QString& itemKey);

  /// Get list of all registered item names
  QStringList names() const;

  /// Register items with the factory
  /// Method provided for convenience - Should be overloaded in subclasse
  virtual void registerItems(){}

protected:

  /// Call the load method associated with the item.
  /// If succesfully loaded, add it to the internal map.
  bool registerItem(const QSharedPointer<qCTKAbstractFactoryItem<BaseClassType> > & item);

  /// Get a Factory item given its itemKey. Return 0 if any.
  qCTKAbstractFactoryItem<BaseClassType> * item(const QString& itemKey)const;

private:
  ...
};
</pre>

** 3 kind of factory: 
*** qCTKAbstractLibraryFactory
*** qCTKAbstractObjectFactory
*** qCTKAbstractPluginFactory

** A factory manage a collection of qCTKAbstractFactoryItem.
<pre>
template<typename BaseClassType>
class qCTKAbstractFactoryItem
{
public:
  explicit qCTKAbstractFactoryItem(const QString& key);
  
  virtual QString loadErrorString()const;
  virtual bool load() = 0;
  BaseClassType* instantiate();
  bool instantiated();
  QString key();
  virtual void uninstantiate();
protected:
  virtual BaseClassType* instanciator() = 0;
  BaseClassType* Instance;
private:
  QString Key;
};
</pre>

* Concrete example(s)
All modules are based on qSlicerAbstractModule
qSlicerAbstractModule provided methods: 
** logic(): This method allows to get a pointer to the ModuleLogic. If no moduleLogic already exists, one will be created calling 'createLogic' method
** widgetRepresentation(): This method allows to get a pointer to the WidgetRepresentation. If no WidgetRepresentation already exists, one will be created calling 'createWidgetRepresentation' method.

** qSlicerCoreModuleFactory: 

*** registerItems -> registerCoreModule -> N * registerCoreModule -> extractName -> registerObject -> registerItem(moduleName)
<pre>
void qSlicerCoreModuleFactory::registerItems()
{
  QCTK_D(qSlicerCoreModuleFactory);
  d->registerCoreModule<qSlicerTransformsModule>();
  d->registerCoreModule<qSlicerCamerasModule>();
}
</pre>

** qSlicerLoadableModuleFactory
*** registerItems -> use QDirIterator -> extractName -> registerPlugin(path, moduleName)
<pre>
template<typename BaseClassType>
bool qCTKFactoryPluginItem<BaseClassType>::load()
{
  this->Loader.setFileName(this->path());
  return this->Loader.load();
}
</pre>
<pre>
template<typename BaseClassType>
BaseClassType* qCTKFactoryPluginItem<BaseClassType>::instanciator()
{
  //qDebug() << "PluginItem::instantiate - name:" << this->path();
  QObject * object = this->Loader.instance();
  if (!object)
    {
    qWarning() << "Failed to instantiate plugin:" << this->path();
    return 0;
    }
  BaseClassType* castedObject = qobject_cast<BaseClassType*>(object);
  if (!castedObject)
    {
    qWarning() << "Failed to access interface [" << BaseClassType::staticMetaObject.className()
               << "] in plugin:" << this->path();
    delete object; // Clean memory
    return 0;
    }
  return castedObject;
}
</pre>

** qSlicerCLILoadableModuleFactory
*** registerItems -> use QDirIterator -> extractName -> registerLibrary(path, moduleName)
<pre>
void qCTKFactoryLibraryItem<BaseClassType>::resolve()
{
  foreach(const QString& symbol, this->Symbols)
    {
    // Sanity checks
    if (symbol.isEmpty()) 
      { 
      continue; 
      }
      
    // Make sure the symbols haven't been registered
    if (this->ResolvedSymbols.contains(symbol))
      {
      qWarning() << "Symbol '" << symbol << "' already resolved - Path:" << this->Path;
      continue;
      }
    
    void * resolvedSymbol = this->Library.resolve(symbol.toLatin1());
    if (!resolvedSymbol)
      {
      qWarning() << "Failed to resolve symbol '" << symbol << "' - Path:" << this->Path;
      }
    this->ResolvedSymbols[symbol] = resolvedSymbol;
    }
}
</pre>