This tutorial is a brief introduction on how to make plugins for Realbasic. This is not how to make a plugin system for your application. The purpose of this is to help others get started making plugins. I found that the plugin documentation was so bad for people that didn't know what they where doing, that it was almost impossible. I also found that there wasn't much in the way of third party documentation on this topic, either. Extremely dissapointed, I trudged though the horrible documentation and pieced together some understanding of what should be done. I've detailed it here for people so they don't have to deal with that mess and be scared away from plugins. This tutorial, for now, will focus on Windows plugins, as I haven't messed with mac and linux plugins. I hope to add those sections latter.
First, you need to download a few things. You need to download the Plugin SDK from Realsoftware. You also need Visual C++ from Microsoft. Unfortionatly, the espress edition doesn't compile dlls, so you have to get a better version. You might be able to use other compilers, but I don't know how to get them to work. Start a new Win32 project, select that you want to make a dll, and then remove nearly all the pre-generated code. Aaron Ballman makes this part of the process rather clear. You basically want a blank dll project.
Now, note where your project is saved, and minimize the ide. Open up the SDK folder, and find "winheader++.h", "rb_plugin.h", "REALplugin.h", and "PluginMain.cpp". Copy these files over to your project folder, and open the project back up. Add these new header and source code files to your project. In the (blank) project header file, #include winheader++.h and rb_plugin.h. For now, also add the line "extern "C" {}". We'll add stuff here, latter. In your main (blank) .cpp file, #include your projects header that you where just in. Finally, add "void PluinEntry(void) {}" to the bottom. We'll add stuff here, too, latter.
The only problem with this is that there isn't a free version of Visual C++ that can compile DLLs. Because I have Visual Studio, this wasn't a problem for me, but it can easily be a problem for other people. So I found out how to do all this in one of the most popular free windows compilers Dev-C++
After downloading and installing Dev-C++, start a new DLL C++ project. Create a new folder for your project and save everything in there. As before, delete all the pre-generated code in both the dllmain.cpp and the dll.h files. Copy the include files like before into your folder and import them into your project. Now add the #includes, functions, and extern "C" block like before. Now go to the project options menu. Go to Parameters and add the following at the end of the "Compiler:" and "C++ compiler" lines. "-D IGNOREQT -include "WinHeader++.h"". This is rather important, as, without it, there will be hundreds of erros when you compile. Also, edit the linker line to be "--export-all-symbols --add-stdcall-alias". Now everything should be set up right for Dev-C++.
We now could compile this to a plugin that would do absolutly nothing. Kinda dull, but we have an empty plugin. For more details on this part of the project, just read that post on Aaron Ballman's site. It explains it in good detail
To define a function to be used in the plugin, first create the function. Simple enough. Lets say we want to have a function that will add five to a number passed to it and return the result. Not something that needs to be in a plugin, but it is easy enough for understanding what we are doing. Add the following between the #includes and the PluginEntry function in the main file.
int add5func(int v)
{
return v+5;
}
That defines the function, just as it would in normal C++, or, with modifications, in RB. Now, right below that, add the following
REALmethodDefinition add5defn = {
(REALproc) add5func
REALnoImplementation
"Add5(num as integer) as Integer" };
This weird bit of code creates a method definition for the plugin APIs. The first line gives it the address of the function we are defining. The second line is used if we want to have a second function as a setting method. As we don't need that, we pass REALnoImplementation, which says we don't want that. Finally, we have a line that is what RB sees as the function definition. We are getting close. Add the following line in the PluginEntry block
REALRegisterMethod( add5defn );
This will do the registering of the method so that RB can use it. The thing to note is that we are passing in the REALmethodDefinition for the function, not the function itself. One last thing, is that we have to put the function definition in the extern C block in the header. Go there and put the following inside the brackets (probably on a new line)
int add5func(int v);
This last bit may not be necessary. I've heard conflicting arguments on either side, but it doesn't seem to hurt to put all the functions you define there. Even for class methods. Although, when I made a class, I didn't put the functions there, so I guess it doesn't mater.
Save your project. Go up to build, and have it build your project. Not debug, as I don't know how to have it just debug your almost-plugin. Now comes the weird part. Open up the SDK folder, and go to the Plugin Converter folder. Open that RB project and either compile it or run it. I compiled it as I didn't need to edit it and I was going to use it often. You might be thinking, "Why do I need to convert the plugin? I don't have one to convert" and you're right. The converter is rather missnamed in my opinion. It seems to have been created a while ago when it was mostly needed to convert old style RB plugins to new ones. But it is still used for new plugins.
Open up the folder that contains your dll that you just made, and also open up the converter program. Click the "Create New" button near the bottom. This brings up a new window with a bunch of folders. Drag the dll into this window, then drag it up so that it is under the windows folder. Give the plugin some kind of name, even though I don't know where this comes into play, and click save. Here, give it a real good name, as this is what people will see. Save it to the RB plugin folder that should be in the main RB directory where you installed it. You should now have a real plugin. Congradulations!
Close out of RB if it is open, and hide all the other windows to clean up your space (or move them to your other monitor, if you are that good). Now open RB up and create a new project. The reason for closing and opening RB is because RB loads plugins when it opens only. So if it was still open, your plugin wouldn't be recognized or be able to be used. In some event, like the window's open event, add "msgbox(str(add5(7)))". As you type add5, a little message might show up saying where the fucntion comes from. Autocomplete should also work for the function. Run the program and a messagebox should show up with the number 12. If so, then everything worked. Otherwise, you messed up somewhere. Double check your work, then let me know if I made a mistake ;)
Comming soon
Comming soon