Inheritance diagram for GKPlugin:

Public Member Functions
	GKPlugin ()

virtual QString	verify ()=0

const QString &	getName () const

	if (base)

Public Attributes
ConvertToSubClassCode Py_BEGIN_ALLOW_THREADS GKPlugin *	base = (GKPlugin*)sipCpp

	sipType = 0

Detailed Description

A plug-in is a shared library that implements one or more than one modifications in the system. It can add new classes (and types), new editors, new menus, new functions,...

A plug-in have full access to the Kernel and the GUI of the system. Note, but, the GUI cannot be presented (in a console application only the Kernel is available).

The plug-in has a home, a variable that points to the folder where files related to the plug-in will be stored (as preferences). This home can be different from the system home (where the Aimsun Next application has been installed).

Main plug-in methods

In order to implement a plug-in the developer will, possibly, rewrite some of the following methods:

GKPlugin::install: add here any initialization needed by the plug-in that is independent of the GUI (as register new types and filters).
GKPlugin::initGui: initialize the GUI of the plug-in: add menus and any other GUI element (note that a system without a GUI will never call this function).
GKPlugin::docOpened: initialize any aspect of the plug-in related to the just opened model (note that in a system without a GUI the parameter gui will be None).
GKPlugin::guiReady: called after restoring (or creating a new model) and all the GUI elements for that model have been created. So GKPlugin::docOpened is called after restoring all the data but before creating any GUI element and GKPlugin::guiReady after creating that GUI (so after GKPlugin::docOpened)
GKPlugin::docClosed: clean up just before closing a document.
GKPlugin::about: to show and about window (if GUI is present) or a text message in the standard output (if no GUI is present)

And he will set the variable GKPlugin::name with the name and version of the plug-in in the GKPlugin constructor.

Plug-in Factory

When the library that contains a plug-in is loaded Aimsun Next will create a new plug-in object using its factory, a C function. Its name will be the name of the plug-in as found in the plug-in XML file (see bellow) plus Factory. That is, is the name of the plug-in is MyPluging then the function that will create the plug-in will be:

extern "C" EXPORT_MACRO GKPlugin * MyPlugingFactory()
{
    return new MyPluging();
}   

For a description of what EXPORT_MACRO means see the GKObject documentation.

Plug-ins store and restore

Plug-ins can store data in the model in several ways. One is creating new objects taht will be saved as part of the model catalog. Other way is specifying preferences. The last way is to use the store and restore methods.

The store method returns a XML string with data that have to be saved with the model but that is neither part of the catalog nor a part of the preferences. The format of the XML will be: <plugin name="NAME">...</plugin> Where ... is the plug-in specific data. Aimsun GKModel will generate the <plugin> lines so the plug-in will only produce a string with the "..." data.

The restore will decode and use this data from the received QDomNode. This node will point to the <plugin></plugin> node.

In both cases the data is related to a particular model. For data that is not model related (system related data) the plug-in can write it in a file in its home folder. This data can be written to a file in the object destructor and can be read in the install method (and not in the object constructor as the plug-in home folder as not yet been set).

Plug-ins and the User Interface

If important to know that a plug-in is shared between all the possible opened documents and that in each document an instance of GKModel and (maybe) GGui exist. So, the plug-in cannot keep references to the model or the gui (after a docOpened call).

In order to know the context of a call, that is, in which GGui and then in which GKModel the operation has been requested the plug-in can use the findGui() method. This will return the current gui from where the action originates. Note that only SLOTS methods (or methods called directly by a slot) called by a signal can use successfully the GKPlugin::findGui call (as it used QObject::sender() ).

When a slot is called by a signal originated in a menu item then QObject::sender() do not contain the reference to the caller and, then, the GGui cannot be found. In order to avoid this the user must add information about in which GGui and menu the menu item has been created using the method registerMenuItem.

The helper method setEnabledMenuItems will change the enable status of all the menu items created and registered by a plug-in. It's can be used by the plug-in in the docOpened and docClosed methods to enable or disable the menus.

Installing a Plug-in

When Aimsun Next starts it reads all the XML files in the folder AIMSUN_HOME/plungins. Each file contains the definition of one (and only one) plug-in. The name of the file is irrelevant (as long as it is unique).

The file (in XML format) has the following format:

<plugin>
    <name>PLUG-IN_NAME</name>
    <lib>PLUG-IN_LIB</lib>
    <location>PLUG-IN_LOCATION_FILE</location>
    <home>PLUG-IN_NAME</home>
</plugin>

The values for each field are:

name: Plug-in name used to locate the plug-in factory. It's case sensitive. This field is mandatory.
lib: DLL or shared library that contains the plug-in code. Full paths and relative paths (to Aimsun starting folder) are supported. Library extension (dll in windows, so for shared libraries) is optional. It's case sensitive if the file system is. This field is mandatory.
location: QM file that contains the located strings. Aimsun Next will add to this value the name of the current locate (QTextCodec::locale method) and the qm extension. Example: if location value is my_plugin_location_ then the loaded file will be: my_plugin_location_de.qm for a German locale and my_plugin_location_en.qm for an English locale. This field is optional.
home: Home folder for this plug-in. Available using the method GKPlugin::getHome. This field is optional and, if is not present, Aimsun Next will set it to PLUGINS_HOME.

Values in the fields lib, location and home can be specified using the following three variables:

APP_HOME: contains the folder where Aimsun has been installed.
PLUGINS_HOME: the plugins folder.
PLUGIN_HOME: contains the value of the home field. It cannot be used until this field has been defined.

Example:

<plugin>
        <name>MyPlugin</name>
        <home>$PLUGINS_HOME/myplugin</home>
        <lib>$PLUGIN_HOME/myplugin_code</lib>
        <location>$PLUGIN_HOME/myplugin_location_</location>        
</plugin>

This file will make Aimsun to load a plug-in which factory is called MyPluginFactory, with a home set in c:/Program Files/Aimsun/Aimsun Next 22/plugins/myplugin, with the code located in the DLL (in Windows) c:/Program Files/Aimsun/Aimsun Next 22/plugins/myplugin/myplugin_code.dll and, when using a Spanish locale, Aimsun Next will load the location file called c:/Program Files/Aimsun/Aimsun Next 22/plugins/myplugin/myplugin_location_es.qm

Constructor & Destructor Documentation

◆ GKPlugin()

GKPlugin::GKPlugin ( )

Member Function Documentation

◆ getName()

const QString & GKPlugin::getName ( ) const

◆ if()

GKPlugin::if ( base )

inline

References base, GKSystem::getSystem(), and sipType.

◆ verify()

virtual QString GKPlugin::verify ( )

pure virtual

Verify this plug-in (for installation errors for example). Returns a string if something goes wrong (an empty string otherwise).

Implemented in MacroModelPlugin.

Member Data Documentation

◆ base

ConvertToSubClassCode Py_BEGIN_ALLOW_THREADS GKPlugin* GKPlugin::base = (GKPlugin*)sipCpp

Referenced by if().

◆ sipType

GKPlugin::sipType = 0