Next
Previous
Contents
The interface supports four plugin types:
- Import
- Export
- Import with file dialog and working directory functionality
- Export with file dialog and working directory functionality
The first and the second interface type does not support any additional functionality
like file import/export dialog or user defined working directories. These types could be used
for plugins which includes their own file dialogs or maybe which use other data sources/targets
than files (databases e. g.).
The third and second types are used for plugins which extends KMovisto file import/export
funtionality similar to the integrated KMovisto import/export routines. This also includes the
configurable user defined working directories.
The interface type depends on the class where the plugin class is derived from, so each plugin library
is used for one import or export type.
As described above the plugin interface supports four different import/export types which depends on
the class the plugin is derived from. CPluginFileImport, CPluginFileExport, CPluginFileImportDialog and
CPluginFileExportDialog are used for this purpose. Furthermore the six classes CIPluginElements,
CIPluginAtom, CIPluginBond, CIPluginMolecule, CIPluginColor and CIPluginPosition
are used for data exchange and for storing actual settings (Fig. 1).
Fig. 1: Plugin interface class hierarchy
All classes are declared in the namespace kmpi in the header file iplugin.h. Implementations are
found in iplugin.cpp which has to be compiled and linked to your library. To avoid upgrade problems, you should
not edit these two files directly. It is recommended to create your own header and source files. The only thing you
have to do before you start plugin programming is inserting the macro DECLARE_PLUGIN_CLASS(CMyPluginClass) and
the #include "iplugin.h" precompiler command in the header file and inserting IMPLEMENT_PLUGIN_CLASS(CMyPluginClass) in
the source file, where CMyPluginClass is the class you have derived from one of the four base classes CIPluginFile.... You
must not derive your plugin class directly from CIPlugin or CIPluginFile.
Public member functions:
CIPlugin
Detailed Description
CIPlugin is the base class of all types of KMovisto plugins. This class organizes the main plugin informations which are
displayed in the KMovisto Plugin manager. CIPlugin is an abstract class so you never use it directly for plugin
development. The member functions are mostly declared as virtual function which have to be overwritten in derivated classes.
Every inherited plugin class contains protected members elements of type CIPluginElements
and molecule of type CIPluginMolecule which are initialised with
current setting before the import or export starts.
Returns the plugin name which is shown in the plugin manager list.
Returns the plugin description which is shown in the plugin manager description. Overwrite this member function to return
a detailed description of the plugin.
Returns the plugin version. This version is not proofed by KMovisto, so it can be defined free.
Returns the plugin interface version. This version is proofed by KMovisto and should be the same or smaller as the plugin
interface version used by KMovisto.
Returns the type of the plugin. Valid values of enum type KMPI_INTERFACE_TYPE are KMPI_FILE_IMPORT,
KMPI_FILE_IMPORT_DIALOG, KMPI_FILE_EXPORT and KMPI_FILE_EXPORT_DIALOG. They will be defined atomaticaly
in classes derived from CIPluginFile so you should not overwrite this function.
Returns the author of the plugin displayed in the KMovisto plugin manager.
Returns the email address of the plugin author displayed in the KMovisto plugin manager.
Returns the internet address where to find plugin informations or latest versions. This information is also displayed in
the KMovisto plugin manager.
Returns the license of the plugin displayed in the KMovisto plugin manager.
Returns a pointer of the protected member molecule of the plugin instance. This function is usually used by
KMovisto only.
Returns a pointer of the protected member elements of the plugin instance. This function is usually used by
KMovisto only.
Initialises the instance molecule of the plugin instance. Returns KMPI_SUCCESS if successfull
otherwise returns KMPI_ERROR. This function is usually used by KMovisto only.
Initialises the instance elements of the plugin instance. Returns KMPI_SUCCESS if successfull
otherwise returns KMPI_ERROR. This function is usually used by KMovisto only.
This member function is called whenever an instance of the plugin class is created during KMovisto program starts and when
the plugin is added using the plugin manager. Initialisations should be done here rather than in the constructor because there
is a return value of enum type KMPI_RESULT available.
This member function is called whenever an instance of the plugin class is destroyed during KMovisto program exits and when
the plugin is removed using the plugin manager. Any cleanup should be done here rather than in the constructor because there
is a return value of enum type KMPI_RESULT available.
Public member functions:
CIPluginFile
Detailed Description
CIPluginFile inherits CIPlugin and is also an abstract base class. This class declares file import and export specific member
functions.
Returns a pointer of const char pointer type of the xpm bitmap shown in the plugin toolbar button and in the plugin
manager plugin list. The xpm format is not described here but it is a very simple graphic format supported by many graphic
programs. Note that the xpm format has to be little bit different from the usual declaration. The extra const makes the
entire definition read-only:
static const char* xpm[] = {
"16 15 8 1",
"a c #cec6bd",
....
To obtain a uniform look you should define a button xpm's width and height of 16 pixels.
Returns the tool tip of the plugin tool bar button. The tip is a short, single line of text reminding the user of the
plugin's function. It is drawn immediately below the region in a distinctive black-on-yellow combination.
Returns the text of the plugin menu item.
Returns the "What's this?" help text of the plugin. "What's this?" help is part of an application's online help system.
It provides a single window with an explanatory text that pops up when the user asks "What's this?".
Returns the status text of the plugin function. This text is displayed in the status line of the program window when the
plugin function is executed.
Returns the status text of the plugin function when the menu item is highlighted.
This member function is called whenever a file is opened. The absolute filename is found in the reference of file if
the plugin supports the file import and export dialog functionality of KMovisto, that means the plugin has to be derived
from CPluginFileImportDialog and CPluginFileExportDialog otherwise file is an empty string. If file
operation errors occured the return value should be KMPI_ERROR. In this case KMovisto displays the string errorMsg
otherwise this string value is ignored.
Detailed Description
The classes CPluginFileImport, CPluginFileExport, CPluginFileImportDialog and
CPluginFileExportDialog are derived directly or indirectly from CPluginFile and have
no additional member functions. These classes are used to overload functions of the abstract base
classes or declare protected members for the different purposes.
Public member functions:
CIPluginElements
Detailed Description
CIPluginElements is used to define element properties which could be changed during import or export operations. Every
plugin class contains a protected member elements which is initialised with current setting before the import or
export starts. The maximum element number is KMPI_MAX_ELEMENT_NUMBER which is currently set to 109. Note the
valid element symbols above "Ha" (105) are "Unh" (106), "Uns" (107), "Uno" (108) and "Une" (109).
Copies element color and radius.
Returns the atom radius of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the
return value is 0.0f.
Returns the atom radius of the element given by symbol. If symbol is not a valid element symbol the return
value is 0.0f.
Returns the atom color of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the
returned color is black (0, 0, 0).
Returns the atom color of the element given by symbol. If symbol is not a valid element symbol the
returned color is black (0, 0, 0).
Returns the element symbol of the element given by number. If number is not between 0 and KMPI_MAX_ELEMENT_NUMBER the
return value is empty.
Returns the element number of the element given by symbol. If symbol is not a valid element symbol the
return value is 0.
Sets the element radius of the element given by number and returns KMPI_SUCCESS if successfull. If number
is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR.
Sets the element radius of the element given by symbol and returns KMPI_SUCCESS if successfull. If symbol
is not a valid element symbol the return value is KMPI_ERROR.
Sets the element color of the element given by number and returns KMPI_SUCCESS if successfull. If number
is not between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR.
Sets the element color of the element given by symbol and returns KMPI_SUCCESS if successfull. If symbol
is not a valid element symbol the return value is KMPI_ERROR.
Public member functions:
CIPluginAtom
Detailed Description
This class represents a single atom and it's coordinates (atom units) in a molecule.
Copies atom coordinates, number, symbol, radius and color.
Returns the element number of the atom.
Returns the element symbol of the atom.
Returns the element coordinates of the atom.
Returns the element color of the atom.
Returns the element radius of the atom.
Initialise the atom properties by using an instance of CIPluginElements and the atom number. If number is not
between 0 and KMPI_MAX_ELEMENT_NUMBER the return value is KMPI_ERROR otherwise the return value is KMPI_SUCCESS.
Initialise the atom properties by using an instance of CIPluginElements and the atom symbol. If symbol is not
a valid element symbol the return value is KMPI_ERROR otherwise the return value is KMPI_SUCCESS.
Sets the atom position and returns KMPI_SUCCESS.
Sets the atom position and returns KMPI_SUCCESS.
Sets the atom color and returns KMPI_SUCCESS.
Sets the atom color and returns KMPI_SUCCESS if the values red, green and blue are between 0 and 255.
Sets the atom radius and returns KMPI_SUCCESS if radius is 0 or greater.
Public member functions:
CIPluginBond
Detailed Description
This class CIPluginBond represents a single connection between atoms in a molecule. Note that bond properties which are
set only once as bond color or radius are set in the molecule.
Copies connected atoms.
Returns the index of the first bond partner.
Returns the index of the the second bond partner.
Sets the atom indexes of connected atoms. Atom indexes start with 1.
Public member functions:
CIPluginMolecule
set:
- KMPI_RESULT setAtomByNumber(unsigned int index, const CIPluginElements* pElements, unsigned int number)
- KMPI_RESULT setAtomBySymbol(unsigned int index, const CIPluginElements* pElements, const string& symbol)
- KMPI_RESULT setAtomPosition(unsigned int index, const CIPluginPosition& position)
- KMPI_RESULT setAtomPosition(unsigned int index, float x = 0.0f, float y = 0.0f, float z = 0.0f)
- KMPI_RESULT setAtomColor(unsigned int index, const CIPluginColor& color)
- KMPI_RESULT setAtomColor(unsigned int index, unsigned int red, unsigned int green, unsigned int blue)
- KMPI_RESULT setAtomRadius(unsigned int index, float radius)
- KMPI_RESULT setBondColor(const CIPluginColor& color)
- KMPI_RESULT setBondColor(unsigned int red, unsigned int green, unsigned int blue)
- KMPI_RESULT setBondRadius(float radius)
- KMPI_RESULT setTitle(const string& title)
Detailed Description
The class CIPluginMolecule represents a molecule.
Copies all molecule properties.
Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function
returns 0. The atom is defined by a CIPluginAtom type.
Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function
returns 0. The atom is defined by a pointer of an instance of CIPluginElements and the element number of the atom.
Adds a new atom to the molecule and returns the index of the added atom if successfull. Otherwise the member function
returns 0. The atom is defined by a pointer of an instance of CIPluginElements and the element symbol of the atom.
Adds a new bond to the molecule and returns the index of the added bond if successfull. Otherwise the member function
returns 0.
Adds a new bond to the molecule and returns the index of the added bond if successfull. Otherwise the member function
returns 0.
Deletes the atom with index number index and returns KMPI_SUCCESS if successfull. By default all connections
between the deleted atom and other atoms are deleted too if deleteBonds is not set to FALSE.
Deletes the bond between atoms indexed by index1 and index2. If successfull the return value is KMPI_SUCCESS otherwise
the return value is KMPI_ERROR.
By default this member function deletes all atoms and bonds and returns KMPI_SUCCESS if successfull. If deleteAtoms and/or
deleteBonds is set to FALSE atoms and/or bond are not deleted.
Returns the number of atoms in the molecule.
Returns the number of bonds in the molecule.
Returns a pointer to an instance of CIPluginAtom of the atom indexed by indey if successfull otherwise returns NULL.
Returns the element number of the atom indexed by a valid index. Otherwise returns 0.
Returns the element symbol of the atom indexed by a valid index. Otherwise returns an empty string.
Returns the coordinates of the atom indexed by index. If index is not a valid index the coordinates are
set to (0, 0, 0).
Returns the color of the atom indexed by index. If index is not a valid index the color is
set to black (0, 0, 0).
Returns the radius of the atom indexed by index. If index is not a valid index the radius is
set to 0.0f.
Returns a pointer to an instance of CIPluginBond of the bond indexed by index if successfull otherwise returns NULL.
Returns the color of the bond indexed by index. If index is not a valid index the color is
set to black (0, 0, 0).
Returns the radius of the bond indexed by index. If index is not a valid index the radius is
set to 0.0f.
Returns the title of the molecule.
Sets the Atom properties of the atom indexed by index using a pointer to a instance of CIPluginElements and the element number. If
successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the Atom properties of the atom indexed by index using a pointer to a instance of CIPluginElements and the element symbol. If
successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the coordinates of the atom indexed by index using a reference to a CIPluginPosition. If successfull the return
value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the coordinates of the atom indexed by index using x, y, and z coordinates. If successfull the return
value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the color of the atom indexed by index using a reference to a CIPluginColor. If successfull the return
value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the color of the atom indexed by index using red, green and blue values. If successfull the return
value is KMPI_SUCCESS otherwise it is KMPI_ERROR. Note that valid values of red, green and
blue are between 0 and 255.
Sets the radius of the atom indexed by index. If successfull the return value is KMPI_SUCCESS otherwise
it is KMPI_ERROR.
Sets the color of the bond using a reference to a CIPluginColor. If successfull the return value is KMPI_SUCCESS
otherwise it is KMPI_ERROR.
Sets the color of the bond using red, green and blue values. If successfull the return value is KMPI_SUCCESS
otherwise it is KMPI_ERROR. Note that valid values of red, green and blue are between 0 and 255.
Sets the radius of the bond. If successfull the return value is KMPI_SUCCESS otherwise it is KMPI_ERROR.
Sets the title of the molecule and returns KMPI_SUCCESS
Checks if the atoms indexed by index1 and index2 are connected. Returns TRUE if a bond exists otherwise
returns FALSE.
This member function connects atoms automaticly depending on their atom radius and the value of bondFactor.
Atom1 and atom2 will be connected if the following condition is true:
(radius(atom1) + radius(atom2)) * bondFactor >= distance(atom1, atom2)
Public member functions:
CIPluginColor
Detailed Description
This class provides colors based on RGB values.
Constructs a color with the RGB value red, green and blue. Note that RGB values must
be in the range 0 - 255.
Copies RGB values.
Returns the red component of the RGB triplet.
Returns the green component of the RGB triplet.
Returns the blue component of the RGB triplet.
Sets the RGB value to red, green and blue. The arguments, red, green and blue
must all be in the range 0 - 255. If any of them are outside the legal range, the color component is set to the maximum
value of 255 and the return value is KMPI_ERROR otherwise it is KMPI_SUCCESS.
Sets the red component to red. The argument must be in the range 0 - 255. If it is outside the legal range,
the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it
is KMPI_SUCCESS.
Sets the green component to green. The argument must be in the range 0 - 255. If it is outside the legal range,
the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it
is KMPI_SUCCESS.
Sets the blue component to blue. The argument must be in the range 0 - 255. If it is outside the legal range,
the color component is set to the maximum value of 255 and the return value is KMPI_ERROR otherwise it
is KMPI_SUCCESS.
Public member functions:
CIPluginPosition
Detailed Description
This class represents a coordinate (atom units).
Constructs a coordinate with x, y, and z values.
Copies a coordinate.
Returns the x component of a coordinate.
Returns the y component of a coordinate.
Returns the z component of a coordinate.
Returns the distance between two coordinates.
Sets the coordinate and returns KMPI_SUCCESS.
Sets the x component of the coordinate and returns KMPI_SUCCESS.
Sets the y component of the coordinate and returns KMPI_SUCCESS.
Sets the z component of the coordinate and returns KMPI_SUCCESS.
Next
Previous
Contents