How to implement a plugin

Table of Contents

• What do I need to use the Renga API?
• Overview
• Plugin system overview
• Description file contents
• How to create a new plugin in C#
  • Add a reference to the Renga COM component
  • Add a reference to the utility library
  • Implementing the plugin interface
  • Minimal C# example:
• How to create a new plugin in C++
  • Add a DLL entry point (main.cpp)
  • Add a reference to the Renga COM component
  • Implement the plugin interface
  • Minimal C++ Example:
• How to install a plugin
• If the plugin doesn't load

What do I need to use the Renga API?

The requirements to start using the API are as follows:

• Installed Renga;
• Renga Software Development Kit (download);
• Microsoft Visual Studio 2022.

Overview

This page describes the design of Renga's plugin system and contains the instructions to help you author Renga plugins. Please see the sample plugin implementations in [RengaCOMSDK dir]/Samples.

Plugin system overview

A basic Renga plugin consists of:

• the plugin's binary file, which is a regular Windows dynamic-link library or a .NET assembly.
• the description file - an XML file named with the .rndesc extension, which contains plugin description and loading instructions.

Each description file should be placed into its own subdirectory in the Plugins subdirectory of Renga's installation folder. Names of the description file should match the plugin's folder name. For example, for a plugin located in [RengaInstallation]/Plugins/Sample folder, the description file should be [RengaInstallation]/Plugins/Sample/Sample.rndesc.

All plugins are loaded into the Renga process on application start and are unloaded on exit.

Typical folder structure:

[RengaInstallation]/
  Plugins/
    Sample/
      Sample.rndesc                  "description file"
      Sample.dll                     "plugin binary"        
      ...                            "other files that the plugin depends on"

Description file contents

Example Sample.rndesc file:

<RengaPlugin>
   <Name>Sample</Name>                              \<!-- Displayed plugin name -->
   <Version>1.0</Version>                           \<!-- Plugin version -->
   <Copyright>Copyright text</Copyright>            \<!-- Copyright information -->
   <RequiredAPIVersion>2.30</RequiredAPIVersion>    \<!-- Minimum required version of Renga API -->
   <PluginType>Net8</PluginType>                    \<!-- Plugin type (can be in any case) -->
                                                       \<!-- "net" or ".net" for plugins written on .NET Framework (C#, C++/CLI) -->
                                                       \<!-- "net8" or ".net8" for plugins written on .NET 8 (C#, C++/CLI) -->
                                                       \<!-- "cpp", "vcpp" or "c++" for plugins written on Visual C++. Optional, defaults to "cpp" -->
   <PluginFilename>Sample.dll</PluginFilename>      \<!-- Path to the plugin's binary file, either relative to the folder containing the .rndesc file or an absolute one -->
   <Vendor>Renga</Vendor>                           \<!-- Vendor of the plugin -->
</RengaPlugin>

How to create a new plugin in C#

To create your own plugin in C#, create a new class library project in Microsoft Visual Studio.

Add a reference to the Renga COM component

To use the Renga system API, you must add a reference to the Renga COM component. You can do this in two ways:

• Add the following entry to your .csproj file (used in Samples):
  

<ItemGroup>
  <COMFileReference Include="[RengaCOMSDK dir]/tlb/RengaCOMAPI.tlb">
  </COMFileReference>
</ItemGroup>

• Or add a reference through the Reference Manager.

Attention: The reference to the Renga type library must have the "Embed interop types" property set to False. This is necessary for the interop assembly to be generated when building the plugin. The reason is that the Renga .Net SDK libraries also depends on this assembly.

Add a reference to the utility library

• To create a .NET Framework plugin, add a reference to Renga.NET.PluginUtility.dll.
• To create a .NET 8 plugin, add a reference to Renga.NET8.PluginUtility.dll.

Both DLLs are located in the [RengaCOMSDK dir]/Net folder.

Implementing the plugin interface

In the library, add a class that implements the Renga.IPlugin interface (both explicit and implicit implementations are supported).

The interface has two methods:

• bool Renga.IPlugin.Initialize(string pluginFolder), which is called on plugin initialization;
• void Renga.IPlugin.Stop(), which is called when the plugin is being unloaded.

Minimal C# example:

namespace SamplePlugin  
{
  public class SamplePlugin : Renga.IPlugin
  {
     private Renga.Application m_app;
        
     public bool Initialize(string pluginFolder)
     {
        m_app = new Renga.Application(); 
        // TODO: use Renga API -  create Actions, Buttons etc.
        return true; 
     }
 
     public void Stop()
     {
        // Cleanup
     }
  }
}

How to create a new plugin in C++

To create your own plugin in Visual C++, create a new dynamic-link library (DLL) project in Microsoft Visual Studio.

Add a DLL entry point (main.cpp)

Add a new source file main.cpp to define DllMain.

Example of main.cpp:

#include <windows.h>
 
HMODULE DllHandle;
 
BOOL APIENTRY DllMain(HMODULE hModule, DWORD dwReason, LPVOID lpReserved) 
{
  if (dwReason == DLL_PROCESS_ATTACH) 
    DllHandle = hModule;
  return TRUE;
}

Add a reference to the Renga COM component

Add a new source or header files to define your Plugin.

To generate API types from the Renga Type Library, you must both point the compiler to the TLB folder and import the TLB in code.

• Add the TLB folder to your project include paths:
  • Visual Studio-->Project-->Properties-->Configuration Properties-->C/C++-->General-->Additional Include Directories
  • Add: [RengaCOMSDK dir]\tlb (i.e., the directory that contains RengaCOMAPI.tlb)

• Then import the type library in code, placing the import before any Renga C++ SDK headers (or any headers that use Renga API types):

  #import <RengaCOMAPI.tlb>
  #include <Renga/IPlugin.h>

• Alternatively, you can import by absolute path without changing include directories:

  #import "[RengaCOMSDK dir]/tlb/RengaCOMAPI.tlb"
  #include <Renga/IPlugin.h>

Implement the plugin interface

In the library, add a class implementing Renga::IPlugin. It has two methods to implement in the plugin:

• bool Renga::IPlugin::initialize(const wchar_t* pluginPath), which is called on plugin initialization;
• void Renga::IPlugin::stop(), which is called when the plugin is being unloaded.

Then place the EXPORT_PLUGIN(YourPluginClassName); macro after the plugin class declaration.

Minimal C++ Example:

#pragma once
#import <RengaCOMAPI.tlb>
 
#include <Renga/IPlugin.h>
 
class MyPlugin : public Renga::IPlugin
{
public:
    bool initialize(const wchar_t* pluginPath) override
    {
        auto pApplication = Renga::CreateApplication();
        if (!pApplication)
            return false;
        // TODO: use Renga API -  create Actions, Buttons etc.
        return true;
    }
 
    void stop() override
    {
        // Cleanup
    }
private:
    
};
 
EXPORT_PLUGIN(MyPlugin);

How to install a plugin

You need to place the plugin's description file into the corresponding directory of Renga's installation (see the Plugin system overview section above). Any other files, including the plugin binary itself, may be placed arbitrarily. Renga locates the binary file depending on the path stated in the PluginFilename tag of the description file.

Remember to deploy the Renga.NET.PluginUtility.dll assembly (for .NET Framework plugins) or Renga.NET8.PluginUtility.dll assembly (for .NET 8 plugins) and any other resources your plugin might depend on.

You may also want to create your own installer for the plugin. In this case, you should determine the location of the Renga installation.

You can determine it using the InstallLocation attribute in the following registry key:

• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall{5129DC7E-FC1E-45DD-B9C9-82940798C85E} for Renga Standard
• HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall{AD5DA106-F1CF-453A-9E44-510164E2F932} for Renga Professional

If the plugin doesn't load

If some errors prevent the plugin from loading successfully, you can check the application log for details. The log is stored in localappdata%\Renga Software\Renga\AecApp.log.