Improved documentation and extended API.

Libs/PluginFramework/ctkPluginFrameworkLauncher.cpp

@@ -73,46 +73,47 @@ void ctkPluginFrameworkLauncher::setFrameworkProperties(const ctkProperties& pro
 }
 
 //----------------------------------------------------------------------------
-bool ctkPluginFrameworkLauncher::install(const QString& symbolicName)
+long ctkPluginFrameworkLauncher::install(const QString& symbolicName, ctkPluginContext* context)
 {
   QString pluginPath = getPluginPath(symbolicName);
-  if (pluginPath.isEmpty()) return false;
+  if (pluginPath.isEmpty()) return -1;
 
-  if (d->fwFactory == 0) {
+  ctkPluginContext* pc = context;
+
+  if (pc == 0 && d->fwFactory == 0) {
     d->fwFactory = new ctkPluginFrameworkFactory(d->fwProps);
     try
     {
       d->fwFactory->getFramework()->init();
+      pc = getPluginContext();
     }
     catch (const ctkPluginException& exc)
     {
       qCritical() << "Failed to initialize the plug-in framework:" << exc;
       delete d->fwFactory;
       d->fwFactory = 0;
-      return false;
+      return -1;
     }
   }
 
   try
   {
-    getPluginContext()->installPlugin(QUrl::fromLocalFile(pluginPath));
+    return pc->installPlugin(QUrl::fromLocalFile(pluginPath))->getPluginId();
   }
   catch (const ctkPluginException& exc)
   {
     qWarning() << "Failed to install plugin:" << exc;
-    return false;
+    return -1;
   }
 
-  return true;
 }
 
 //----------------------------------------------------------------------------
-bool ctkPluginFrameworkLauncher::start(const QString& symbolicName, ctkPlugin::StartOptions options)
+bool ctkPluginFrameworkLauncher::start(const QString& symbolicName, ctkPlugin::StartOptions options,
+                                       ctkPluginContext* context)
 {
-  QString pluginPath = getPluginPath(symbolicName);
-  if (pluginPath.isEmpty()) return false;
-
-  if (d->fwFactory == 0) {
+  // instantiate and start the framework
+  if (context == 0 && d->fwFactory == 0) {
     d->fwFactory = new ctkPluginFrameworkFactory(d->fwProps);
     try
     {
@@ -126,7 +127,7 @@ bool ctkPluginFrameworkLauncher::start(const QString& symbolicName, ctkPlugin::S
       return false;
     }
   }
-  else if (d->fwFactory->getFramework()->getState() != ctkPlugin::ACTIVE)
+  else if (context == 0 && d->fwFactory->getFramework()->getState() != ctkPlugin::ACTIVE)
   {
     try
     {
@@ -141,14 +142,21 @@ bool ctkPluginFrameworkLauncher::start(const QString& symbolicName, ctkPlugin::S
     }
   }
 
-  try
+  if(!symbolicName.isEmpty())
   {
-    getPluginContext()->installPlugin(QUrl::fromLocalFile(pluginPath))->start(options);
-  }
-  catch (const ctkPluginException& exc)
-  {
-    qWarning() << "Failed to install plugin:" << exc;
-    return false;
+    QString pluginPath = getPluginPath(symbolicName);
+    if (pluginPath.isEmpty()) return false;
+
+    ctkPluginContext* pc = context ? context : getPluginContext();
+    try
+    {
+      pc->installPlugin(QUrl::fromLocalFile(pluginPath))->start(options);
+    }
+    catch (const ctkPluginException& exc)
+    {
+      qWarning() << "Failed to install plugin:" << exc;
+      return false;
+    }
   }
 
   return true;
@@ -250,3 +258,20 @@ QString ctkPluginFrameworkLauncher::getPluginPath(const QString& symbolicName)
   return QString();
 }
 
+//----------------------------------------------------------------------------
+QStringList ctkPluginFrameworkLauncher::getPluginSymbolicNames(const QString& searchPath)
+{
+  QStringList result;
+  QDirIterator dirIter(searchPath, d->pluginLibFilter, QDir::Files);
+  while(dirIter.hasNext())
+  {
+    dirIter.next();
+    QFileInfo fileInfo = dirIter.fileInfo();
+    QString fileBaseName = fileInfo.baseName();
+    if (fileBaseName.startsWith("lib")) fileBaseName = fileBaseName.mid(3);
+    result << fileBaseName.replace("_", ".");
+  }
+
+  return result;
+}
+

Libs/PluginFramework/ctkPluginFrameworkLauncher.h

@@ -59,13 +59,13 @@ public:
   static void setFrameworkProperties(const ctkProperties& props);
 
   /**
-   * Install the plugin with the given symbolic name in the Plugin
-   * Framework.
+   * Install the plugin with the given symbolic name using the provided
+   * <code>ctkPluginContext</code>.
    *
    * <p>
    * This method instantiates and initializes an instance of a
-   * ctkPluginFramework object, if there is no framework already
-   * initialized.
+   * ctkPluginFramework object, if no plugin context is provided and
+   * if there is no framework already initialized.
    *
    * <p>
    * The plugin is searched in the paths previously given by calls
@@ -73,33 +73,38 @@ public:
    * CTK plugin installation path.
    *
    * \param symbolicName The symbolic name of the plugin to install.
-   * \return <code>true</code> if the plugin was found and successfully
-   *         installed, <code>false</code> otherwise.
+   * \param context The plugin context used for installing the plugin.
+   * \return The plugin id if the plugin was found and successfully
+   *         installed, <code>-1</code> otherwise.
    */
-  static bool install(const QString& symbolicName);
+  static long install(const QString& symbolicName, ctkPluginContext* context = 0);
 
   /**
-   * Start the CTK Plugin Framework and/or the plugin with the given
-   * symbolic name.
-   *
-   * <p>
-   * This method creates and initializes the CTK Plugin Framework if it
-   * has not been previously initialized and starts it. It then optionally
-   * starts the plugin with the given symbolic name and start options.
+   * This method instantiates, initializes, and starts an instance of a
+   * ctkPluginFramework object, if no plugin context is provided and
+   * if there is no framework already running. It then installs and
+   * starts the plugin with the given symbolic name (if not empty).
    *
    * <p>
    * If a symbolic name is given, the plugin is searched in the paths previously given by calls
    * to #addSearchPath(const QString&, bool) and in the default
-   * CTK plugin installation path.
+   * CTK plugin installation path and is started using the given <code>options</code>.
+   *
+   * <p>
+   * If a plugin context is provided, this context is used to install the plugin,
+   * otherwise the Plugin Framework context is used.
    *
    * \param symbolicName The symbolic name of the plugin to install.
    * \param options The options used to start the plugin.
+   * \param context The plugin context to use for installing the plugin.
    * \return <code>true</code> if the plugin was found and successfully
    *         installed, <code>false</code> otherwise.
    *
    * \see ctkPlugin::StartOption
    */
-  static bool start(const QString& symbolicName = QString(), ctkPlugin::StartOptions options = ctkPlugin::START_ACTIVATION_POLICY);
+  static bool start(const QString& symbolicName = QString(),
+                    ctkPlugin::StartOptions options = ctkPlugin::START_ACTIVATION_POLICY,
+                    ctkPluginContext* context = 0);
 
   /**
    * Get the plugin context for the Plugin Framework.
@@ -118,11 +123,11 @@ public:
   static QSharedPointer<ctkPluginFramework> getPluginFramework();
 
   /**
-   * Append a path to the PATH environment variable.
+   * This is a utility method to append a path to the PATH environment variable
+   * on Windows platforms.
    *
    * <p>
-   * This method appends the given path to the PATH environment variable.
-   * It does nothing on non-Windows platforms.
+   * This method does nothing on non-Windows platforms.
    *
    * \param path The path to be appended to PATH
    */
@@ -156,6 +161,18 @@ public:
    */
   static QString getPluginPath(const QString& symbolicName);
 
+  /**
+   * Get a list of symbolic names for the plugins in <code>searchPath</code>.
+   *
+   * <p>
+   * The symbolic names are deduced from the shared libraries found in
+   * <code>searchPath</code>, which may not represent loadable CTK plugins.
+   *
+   * \param searchPath The path to look for plugins.
+   * \return A list of potential plugin symbolic names.
+   */
+  static QStringList getPluginSymbolicNames(const QString& searchPath);
+
 private:
 
   static const QScopedPointer<ctkPluginFrameworkLauncherPrivate> d;