Python GME (PyGME) Component Generator

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, or it can be opened and executed from inside a Python environment, like PythonWin or Komodo.

    > 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.

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: After generation, the component module, GMEComComponent.py, and SelfRegistration.py must reside in a folder that is 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.

Python components access GME COM interfaces through PythonCOM.  This is different from the high-level interfaces generated for BON and BON2 components.  The best source of reference for the definition of these interfaces are the IDL files distributed with GME.  GME and PythonCOM's implementation of COM collections means that collections are returned as native Python lists. 

Care must be taken when using the COM interface pointers that PythonCOM has wrapped as objects.  For example, if an interface returns an IMgaFCO object and the underlying object is an IMgaModel, then this object must be cast before members of the IMgaModel interface are accessed.  The base class from which all Python components created by the framework are derived provides two members that can be used to access the typelib modules generated by PythonCOM: mga and meta.  These correspond to the mga.idl and meta.idl, respectively.  To perform the cast described above, one would say:

    > someModel = self.mga.IMgaModel(someFCO)

As a convenience, the GMEComComponent base class also provides a Logger member.  This method can be used to write messages to the GME console.

Interpreter components need only implement the component's InvokeEX method to be fully implemented. Addons must register their interest in object events in their Initialize method and then implement service routines for global and objects events. The framework provides boilerplate for these implementations.