Registering UI Plugins in the Windows Registry | Registration with a Plugin Point in STK (Category Registration)

User Interface (UI) Plugin Registration for COM UI Plugins

Once a COM UI plugin component has been built, it must be registered in the windows registry as well as being registered with a plugin point in the hosting environment. After the COM UI plugin is properly registered, it can be deployed to other computers for use by others.

Registering Engine Plugins in the Windows Registry

Because each COM UI plugin component is a COM object, it must follow certain COM paradigms. Most importantly, each component must be registered for use in the Windows registry with a unique GUID (Globally Unique Identifier). You must have administrative rights to add components to the Windows registry.

Visual Studio provides the GuidGen.exe program that generates unique GUIDs. Access the GUID creation tool from the Tools menu in Visual Studio. For users without Visual Studio, download the Windows Script Component Wizard from www.msdn.com/downloads which can also generate GUIDs. It is very important not to have more than one component registered in the Windows registry with the same GUID.

Before registering the components, if you have Microsoft AntiSpyware application actively running, you will have to perform one of the following tasks:

Allow the running of these scripts via the MS AntiSpyware applications options menu.
Or run the script, and when it asks for it to allow the script, check the box indicating "Remember this action".

LicenseSet

<LicenseSet> provides a mechanism to specify STK licenses required to run the UI plugin. If you are wondering if the UI Plugin has sufficient licenses to run, you can check on the Plugin page.

Open the Edit - Preferences menu.
Select the Ui Plugins page.
Select a UI plugin from the Plugins list.
In the Advanced Options field, click the Details button.
Locate the Has sufficient licenses field. If you have the necessary licenses, it will say "true." If you don't have the licenses, it will will say "false."

Compiled Plugins

Compiled components are contained in a dynamic link library, whose filename has an extension 'dll'. To register the component, create a command window (under the Start menu, hit "Run ...", type 'Command' and hit OK). Change your directory (using cd) to that of the file. At the command prompt, type 'regsvr32 YOUR_UIPLUGINNAME'. For example:

regsvr32 YOUR_UIPLUGINNAME.dll

Registration with a Plugin Point in STK (i.e., Category registration)

To register your COM UI plugin with the hosting environment, you need to list it in an XML registration file.

The registration file has the following form:

<?xml version = "1.0"?>
<AGIRegistry version = "1.0">
<CategoryRegistry>
<Category Name = "UiPlugins">
<UiPlugin DisplayName = "Optional Display Name" ProgID = "YOUR_ProgID" File = "Filepath/NameofComponent.dll" DisplayName = "YOUR_DISPLAYNAME">
</Category>
</CategoryRegistry>
</AGIRegistry>

Tags (e.g., Plugin) and attributes (e.g., DisplayName) are case-sensitive.

You may choose to create a new XML file for each plugin you create; or you may choose to use one file to register multiple plugins (even multiple plugins to multiple categories). Each file is capable of registering multiple plugins (here shown using the <UiPlugins> tag) and registering multiple categories (here shown using the <Category> tag). You need not register all plugins of the same Category in the same file. The ProgID is the Program Identifier you chose to associate with your plugin's GUID.

Display Name

In COM UI plugins, The DisplayName is used as a user-friendly short-hand for the ProgID listed. You may choose any DisplayName, but it must be unique amongst all registered plugins of the same category. See the sample registration files for the official category name of a plugin point.

Version Information

You can add version information to the xml manifest file, as shown in the following COM UI plugin example. (User-defined values are in green.)

 
 <UiPlugin ProgID="Agi.Ui.Plugins.CSharp.Basic" 
     File="C:\Source\DeveloperKit\CodeSamples\Extend\Ui.Plugins\CSharp\Basic\bin\Debug\Agi.Ui.Plugins.CSharp.Basic.dll" 
     DisplayName="Basic CSharp Plugin">          
            <VersionInfo Version="Version Number">
               <Publisher>Company Name</Publisher> 
               <SupportUrl>http://companyname.com/UIPlugin/</SupportUrl> 
               <Creator>Developer Name</Creator> 
               <Description>Description of UI Plugin</Description> 
            </VersionInfo>
  </UiPlugin>

You can view this version information from the STK GUI, by selecting Preferences->Ui Plugins from the Edit menu, and clicking the Details... button under Advanced Options.

Manifest Location

When STK starts, it searches for xml files contained in identified folders and registers all plugins declared in each xml file found. Any changes made to these files after start-up will not take effect until the next time the application starts. STK looks at the following folders for xml plugin registration files:

<STK install folder>\STK 13\Plugins
<STK all users area>\STK 13\Config\Plugins
STK ProgramData\AGI\STK 13\Plugins

XML registration files located in the following folders are available for every user:

<STK install folder>\Plugins
<STK all users area>\Plugins

XML registration files located in <STK user area>\Config\Plugins will be available only for that user.

You may also want to learn more about:

Extend the User Interface Using HTML Pages

Extending the Engine