Monday, 12 January 2015

Metasequoia 4 Plugins – Getting Started

New features can be added to a registered version of Metasequoia by installing plugins.

A plugin is a *.dll (dynamic link library) file.

A *.dll is a type of program created within a software development environment such as Lazarus, Delphi, Visual Studio, CodeBlocks, Orwell's DevCPP, NetBeans, ZinjaI, Pelles C, Falcon C++, CodeLite or text editor/compiler/linker combination.

A *.dll cannot be executed by double clicking on it for instance, but must be loaded by another program and just contains coded functions which are used by the other program.

tetraface Inc. provides a Software Development Kit (SDK) that must be used to write plugin *.dlls for Metasequoia.

In this post I will outline the process of building the plugin examples included in the SDK.

Download the latest Metasequoia Plugin SDK and extract the zip. [link]

Download latest Metasequoia Plugin SDK

The SDK was written in Microsoft’s Visual Studio so it is easiest to use Visual Studio to create the plugins. The plugins are written in the C++ language.

Microsoft have recently released a professional version of Visual Studio 2013 free for personal use so download that Community version instead of the Express version. [link]

You can download the DVD ISO Image (6GB) to install offline or download the web installer and install while connected to the internet.

Download Visual Studio 2013 Community Edition

While on the same web page scroll down to Additional Software and download MultiByte MFC Library for Visual Studio 2013.

Download Multibyte MFC Library for Visual Studio 2013

One of the projects included in the SDK requires a third party code library called WTL (Windows Template Library).

Download the latest version of WTL and extract the zip. [link]

Download latest WTL release

Install Visual Studio and then install the MultiByte MFC Library.

You will have to register Visual Studio 2013 Community Edition to keep using it after 30 days.

You register it by signing in with your Microsoft account while connected to the internet.

Register Visual Studio

Run Visual Studio and click File>Open>Open Project/Solution…, browse to where you extracted the SDK zip and open the solution file, “mqsdk433/mqsdk/mqsdk.sln”.

The SDK solution file may have been created in an earlier version of Visual Studio and if so Visual Studio will ask to upgrade the projects and solution. Click “OK” to the perform the upgrade.

Upgrade projects from older version of Visual Studio

The output from the conversion will be displayed in your browser and as long as there are zero errors for each project everything is okay.

Click “OK” in the security warning dialogs and all the projects in the solution should be opened in Visual Studio.

All the projects in the solution are displayed in the Solution Explorer window.

Projects displayed in Solution Explorer

The project listed in Bold font is the StartUp Project.

The Using Visual Studio section of the SDK help file, “mqsdk433/mqsdk_en.html”, says that WTL is required for the StationSpy and WTLStation projects but this is only true if using the Metasequoia 3 SDK.

tetraface Inc. has rewritten the StationSpy project to use the new window components provided in Metasequoia 4 and so no longer needs WTL.

Right click on the WTLStation project in the Solution Explorer window and select Properties from the pop up menu.

Access the properties for WTLStation project

In the WTLStation Property Pages change the Configuration drop down to “All Configurations”.

Change to All Configurations

Click on the VC++ Directories item in the left pane and then click on Include Directories to get the drop down arrow to appear.

Use the drop down and click on <Edit…>.

Edit the Include Directories

In the dialog click the folder button to create a new entry and then click the ellipsis (…) button to open the Select Directory dialog.

Add new entry

Browse to the WTL folder you extracted earlier and select the “Include” folder inside.

Select WTL Include folder

Click OK in the Include Directories edit dialog.

Click OK to add WTL Include folder

Click OK in the WTLStation Property Pages to save the change.

Click OK to save modified properties

Now the WTLStation project knows where to find the WTL code it needs.

In Visual Studio change the active configuration from “Debug” to “Release”.

Change Build Configuration to Release

The Debug configuration is used for testing and investigating your program while Release is the version that is shipped to the end user.

The Debug version contains extra code added by Visual Studio that is required for interrupting the program or reporting values and so has a larger size on disk.

Click BUILD>Build Solution which will build every project in the solution and create all the plugin *.dlls.

Because WTLStation is the selected project the other option in the BUILD menu is to build only WTLStation.

Build solution

After a short time Visual Studio finishes building all the projects but reports 4 errors and 6 warnings.

Build finished with errors

The 4 errors all apply to the ExportRIB project so ExportRIB is the only plugin we failed to create. I won’t bother fixing the error at this time.

Warnings do not stop the creation of a program or *.dll but good programmers take the advice from the warnings and rewrite the code so no warnings appear. I won’t bother fixing the warnings at this time.

To find where Visual Studio created our *.dlls, right click on a project and click “Open Folder in File Explorer”.

Location of project folder

The *.dll will be in a the “Win32/Release” folder. For the Debug configuration the *.dll will be in the “Win32/Debug” folder.

To install the plugin into Metasequoia, run Metasequoia, go to Help>About plug-ins and click the “Install” button.

Install the plugin into Metasequoia

Navigate to the *.dll file and open it. Metasequoia will let you know whether installation was successful or not.

Successful installation

The plugins are available in one of six areas of Metasequoia.
  • Command plugins appear as a button in the Command Panel
  • Station plugins appear as a menu item in the Panel menu
  • Object plugins appear as a menu item in the Object menu
  • Select plugins appear as a menu item in the Selected menu
  • Create plugins appear as a menu item in the Object>Create menu
  • Import plugins appear as a file type in the Open File dialog
  • Export plugins appear as a file type in the Save As File dialog
When Metasequoia installs a plugin it copies the *.dll to a folder in the Plugins folder that has the same name as the type of the plugin.

Here is an image of the WTLStation plugin we built.

The WTLSation plugin

Visual Studio offers another way to install third party code libraries for a project using an extension called Nuget Package Manager. This could have been used to install WTL into the WTLStation project.

Installing and using Nuget is discussed in this post.[link]


No comments:

Post a Comment