Open “mqsdk_en.html” which is found in the SDK root folder and click “Using Visual Studio” to open the instructions for writing a plugin for Metasequoia.
We configured the solution in the previous post so can jump to step 3 of the instructions and add a new project to the solution.
You should give your project a unique name so the *.dll has a unique name.
Metasequoia will not load two plugins of the same category if they have the same names.
I will prefix all my plugins with “sap”.
Set up the configurations to build a 64 bit version if you wish by following the instructions.
The instructions suggest to select one of the sample plugins that match the category of plugin you wish to create and copy the *.cpp file of that sample plugin to your plugins project folder and rename it.
I will instead create a blank *.cpp and only use the sample *.cpp as a reference.
I want my plugin to act on the current object so will study either the Lathe or Wired *.cpp file for reference. An object plugin appears in the Object menu in Metasequoia.
Plugins can be written in two ways.
The first way uses functions and the second way uses classes.
The Wired plugin uses classes which you can see by the fact that MQBAsePlugin.cpp is included in the Wired project’s source files.
Also examining the Wired.cpp file you see the following line,
class WiredPlugin : public MQObjectPlugin
which means the Wired plugin is declared as a class which is derived from the base class MQObjectPlugin.
The Lathe plugin uses functions to implement the plugin and since I believe this way to be more straightforward I will use Lathe.cpp as my reference.
The next step is to add MQInit.cpp and a blank myplugin.cpp to our plugin project.
Right click the project in the Solution Explorer window and select Add>Existing Item and browse to MQInit.cpp which is found in the root folder of the SDK and click “Add”.
Right click on the project again and select Add>New Item, select C++ File , name it “myplugin” and click “Add”.
Set the Output and Intermediate directories for all configurations and platforms to “$(Platform)\$(Configuration)\” as per the instructions.
Note by default new projects use the Unicode character set.
All the sample projects use the Multi-Byte character set (MBCS) and I think tetraface Inc. suggests to use MBCS to avoid problems compiling their code.
In the Project’s Property Pages for All Configurations, go to Configuration Properties>General>Character Set and use the drop down arrow to select the Multi-Byte character set.
You must install MBCS for Visual Studio 2013 for the Multi-Byte character set to be available.
Set the Additional Include Directories for all configurations to “..” as per the instructions. Remember to click OK to save the changes.
The next step is to write the code in the myplugin.cpp file to create your plugin.
Open myplugin.cpp and Lathe.cpp in the editor by double clicking on them in the Solution Explorer window and study Lathe.cpp.
After the comment section we see a define, a list of included files, a global variable declaration and a function declaration.
We do not need to copy all these lines to our source file because we won’t be using a dialog to get user input.
I have renamed the C library include files to the C++ convention in the above screenshot and renamed the function.
Next in Lathe.cpp is the DllMain function. My understanding is that a DllMain function is not required for DLLs but in this case copy it as is because the global variable hInstance is initialised in DllMain.
We probably won’t use hInstance in this plugin though.
Next in Lathe.cpp is the MQGetPlugInID function. This is a function required to be in all plugin categories as detailed in the API reference.
Go to the API Reference section of the “mqsdk_en.html” start page.
Click on “Plug-in functions” in the left menu to see the list of functions that must be included in each category of plugin.
What you have to do in this function is choose two hexadecimal numbers.
The product number is a number used to identify the author of the plugin and is the same for every plugin that author creates.
The ID number is a number that identifies the plugin and an author would have a unique ID for every different plugin they create.
If you don’t plan on distributing your plugins it doesn’t matter what product number you choose but otherwise you should choose a number that is not already being used.
Check the list of plugins at siobi.info [link] to see which product numbers are already used by the authors because Metasequoia will not load two plugins with the same product and ID numbers.
Copy the MQGetPlugInID function to your source file and replace the numbers with the hexadecimal numbers you chose.
Next in Lathe.cpp is the MQGetPlugInName which is also required for each plugin category.
This function is used to display the plugin name for the selected plugin in Metasequoia’s Help>About Plug-ins dialog.
Next is the MQGetPlugInType function which is required for each plugin category.
Copy the function to your source without change since it returns the correct type.
Next is the MQEnumString function which is required for Object plugins. The text in this function appears as the text for the plugin in Metasequoia’s Object menu.
Next is the MQModifyObject function which is only required for Object plugins.
This function is called when the plugin’s menu item is clicked.
To keep this function tidy it seems the convention is to have this function call another function that contains the code that does the actual modifying.
Copy this function and change the name of the function called so it is the same as the name in the function declaration at line 21.
Now all we need to do is code the myfunction function to do what we want our plugin to do.
You will need some knowledge of C/C++ and use the API reference to see what functions are available to use from Metasequoia. Studying the samples in the SDK will also help.
myfunction will do nothing except return TRUE at the moment.
We have all the functions we need now to build the plugin.
It will not do anything but we can test it to see if,
- it is loaded by Metasequoia
- appears in the Object menu
- appears in the About Plug-ins dialog.
Click BUILD>Build yourprojectname to create the *.dll. Make sure you are building for your platform, 32 or 64 bit.
Right click on the project in the Solution Explorer window and select “Open Folder in File Explorer”.
Navigate to the folder containing the *.dll which in my case was “Win32/Debug/” and copy the *.dll file into the Metasequoia/Plugins/Object folder.
Run Metasequoia. Any errors loading the plugin should be reported on start up.
The plugin appears in the Help>About Plug-ins dialog and is activated from the Object menu.
If you wish to use the Visual Studio debugger to test the plugin the instructions are in the Using Visual Studio section of “mqsdk_en.html”.
In the Property Pages for the Debug configuration, set the Configuration Properties>Debugging>Command to the path to Metaseq.exe.
Using the dropdown arrow and the Browse option is probably the simplest way to do this.
Now if you start debugging in Visual Studio it will run Metasequoia.
You would put a breakpoint in your source code and use your plugin in Metasequoia to trace your function.
Every time you create a new build of your plugin you have to copy it to the correct folder in Metasequoia’s Plugins folder to test it.
You can set a command in Visual Studio to do this automatically if you wish although depending on what OS you are using it may require to run Visual Studio as administrator.
In the Property Pages for the Debug configuration, go to Configuration Properties>Build Events>Post-Build Event>Command Line and enter a command to copy the *.dll to Metasequoia’s Plugins/Object folder.
The values for the macros which are designated like $( … ) are displayed from the Edit dialog which appears as an option when you use the drop down arrow.
prev | next
No comments:
Post a Comment