plugin.h File Reference

#include <openbabel/babelconfig.h>
#include <openbabel/dlhandler.h>
#include <string>
#include <iostream>
#include <vector>
#include <map>
#include <sstream>
#include <cstring>

Go to the source code of this file.

Classes
struct	CharPtrLess
class	OBPlugin

Namespaces
	OpenBabel

Macros
#define	MAKE_PLUGIN(BaseClass)
#define	OB_STATIC_PLUGIN(className, instanceName)

Functions
std::vector< std::string >	EnableStaticPlugins ()

Detailed Description

Simplify 'plugin' classes to be discovered and/or loaded at runtime.

The code in this file makes it easy to make 'plugin' classes. These classes are derived from a base class, like OBFingerprint. The derived classes ('sub-types' like fingerprint2) usually have a single instance. Plugin classes are only discovered at runtime, so no existing code needs to be changed when adding a new derived class. In some builds the new code can be added or removed by just moving a DLL or so file. The plugin classes derived from any base class (including new ones) type can be listed from the commandline.

Step-by-Step Instructions

1) In the header file for YourBaseClass (which handles whatsits). Make sure to include the plugin.h header , derive the class from OBPlugin and in its definition add the MAKE_PLUGIN macro and a function TypeID() containing a simple descriptor of the type

#include <openbabel/plugin.h>
class YourBaseClass : public OBPlugin
{
 MAKE_PLUGIN(YourBaseClass)

 const char* TypeID()
 { return "whatsits"; };

 ...rest of implementation, probably involving virtual functions redefined
 in the sub-type classes
};

See below for what the macro contains.

2) Declare each sub-type in a class derived from the base class and give it a constructor which calls OBPlugin constructor as shown:

class YourSubType1 : public YourBaseClass
{
public:
 YourSubtype1(const char* ID, bool IsDefault=false)
 : YourBaseClass(ID, IsDefault){}

 virtual string Description()
 { return "A description with one or more lines";};

 ...rest of implementation
};

Only the first line of the description is used when the subclasses are listed.

3) Declare a global instance of the sub-type class which specifies its ID. and, optionally, whether it is to be regarded as the default type of YourBaseClass.

YourSubType1 theType1("whatsit2",true);

4) The following functions are available:

YourBaseClass* YourBaseClass::FindType(const char* ID); This returns the default type when ID is NULL or empty.

To list the sub-types of any plugin class use the List which sends to cout by default (or any other ostream if specified).

OBPlugin::List("whatsits")

The ListAsString and ListAsVector functions are alternatives, usable with scripting.

It is also possible to iterate through each sub-type by the following code:

OBPlugin::PluginIterator itr;
for(itr=OBPlugin::Begin("whatsits");itr!=OBPlugin::End("whatsits");++itr)
{
 itr is a std::map::const_iterator
 itr->first is the ID of the subtype;
 itr->second is The OBPlugin* which you will have to cast to your type
}

Since this is not the most beautiful code, it is probably better to use the List methods if possible.

YourBaseClass* MakeNewInstance();

How it works

MAKE_PLUGIN(YourBaseClass) inserts the following code into YourBaseClass:

protected:

 //The collection of sub-types is in a local static variable to avoid
 //any difficulties with the order of initialization of static objects.
 static PluginMapType& Map()
 {
 static PluginMapType m;
 return m;
 }

 //Making the map accessible to the base class (Cannot be used during construction)
 virtual PluginMapType& GetMap()const
 {
 return Map();
 }

public:
 static YourBaseClass*& Default()
 {
 static YourBaseClass* d;
 return d;
 }

 //Constructor registers the sub-type
 YourBaseClass(const char* ID, bool IsDefault=false)
 {
 _id = ID;
 if(ID && *ID && *ID!=' ') //do not register if ID is empty or starts with a space
 {
 if(IsDefault || Map().empty())
 Default() = this;
 Map()[ID]=this;
 //Ensure YourBaseClass is registered in OBPlugin so it can be accessed from the commandline
 PluginMap()[TypeID()] =this;
 }
 }

 static YourBaseClass* FindType(const char* ID)
 {
 if(!ID || *ID==0)
 return Default();
 return static_cast<YourBaseClass*>(BaseFindType(Map(),ID));
 }