This page describes a component generation framework for creating COM-based Python components for the Generic Modeling Environment (
GME).
Both Interpreter and Addon component types are supported. Component modules generated by PyGME expose a class whose method implementations are then completed by the developer.
The framework handles all details of COM and GME component registration.
Since the framework is based on PythonCOM, the user must have the Win32 Extensions for Python installed.
PyGME works with Python 2.7.1 and PyWin32 (build 216). It supports Python versions as early as 2.3 (with related versions of PyWin32.)
PyGME is compatible with GME 11, and has been used with GME versions as early as GME 5.
PyGME is free software distributed under the Vanderbilt-ISIS license.
New Python GME components are specified using a small XML document,
such as the one shown below.
<?xml version="1.0" encoding="UTF-8"?>
<component name="MyPython" version="1.0" type="Interpreter" paradigm="MetaGME">
<iconpath value="Icons/pygme.ico" />
<tooltip value="My Python Component" />
</component>
The attributes on the <component> tag are all mandatory.
name |
Gives an identity to the component.
This name will be used to form the COM class that implements the component.
For example, name="Foo" yields a COM class with the name "MGA.PythonInterpreter.Foo" for an interpreter and
"MGA.PythonAddon.Foo" for an addon.
|
version |
Assigns a version designator to the COM class.
|
type |
Determines the kind of component generated: "Interpreter" for interpreters and "Addon" for addons.
Other values result in a specification error.
|
paradigm |
Name of the GME paradigm for which the generated Python component will be registered.
|
The <iconpath> and <tooltip> tags are optional and only relevant to interpreter components.
iconpath |
Path to a component icon presented in the toolbar for the component's paradigm.
If a relative path, it is considered relative to the folder containing the XML specification file.
(Icons are always registered as absolute paths.)
The file must be a .ico (Windows icon) 32x32 file.
|
tooltip |
A string that is shown when the user mouses over the component's icon in the toolbar,
if an icon is defined.
|
The component generator script can be run from a command prompt as
> PyGME.py [-register[=<system|user>]] [xmlfile]
Switches:
-register |
Requests that the component be registered with COM and GME after generation.
If the value given the switch is user, or if no value is given, then the component is registered in the
current user's registry; otherwise, if the value is system, then the component is registed in the
system-wide registry. Administrative priviledges are required for the latter.
|
Arguments:
xmlfile |
Path to a file that contains an XML specification for the component (see above).
The default is the file 'component.xml' in the same folder as PyGME.py.
|
Examples
> PyGME.py -register mycomponent.xml
> PyGME.py -register=system mysharedcomponent.xml
The generated component is placed into the same folder as the XML specification file.
The name is based on the
name attribute on the
<component> tag in the component's specification.
For example, if the value of the name attribute is 'Foo', then the name of the component is
'Foo.py'. A class inside this module, also named 'Foo', implements the component.
For interpeters, only the
InvokeEx method is exposed in the generated component;
for addons, the
GlobalEvent,
ObjectEvent, and
Initialize methods are exposed.
The remaining component methods are abstracted by the
GMEComComponent base class.
IMPORTANT: | The generated component module, as well as GMEComComponent.py and
SelfRegistration.py, must reside somewhere on the PythonPath. |
To unregister the component after registration, start a Python shell.
Enter the following (assuming a component named 'Foo'):
> from Foo import Foo
> Foo.UnregisterSelf(systemwide)
The
systemwide parameter should be
2 (REGACCESS_SYSTEM) if the component was registered in the System registry (LocalMachine)
and
1 (REGACCESS_USER) if the component was registered in the user registry (CurrentUser).
The constants are defined in
MgaUtil.idl.
To re-register the component, from a Python shell enter:
> from Foo import Foo
> Foo.RegisterSelf(systemwide, iconfolder)
The
systemwide parameter is as defined above for UnregisterSelf.
The
iconfolder parameter is the full path to the folder that contains the component's icon.
This parameter should be omitted for addons and interpreters that do not define an icon.