Requirements
Before we will start the following is required:
- A past .Net programming knowledge. In this tutorial we will only touch C#, although plugins can also be written in VB .net.
- An IDE (Microsoft Visual Studio C# VB).
- MRP2 Plugin Template. This template was created by me to help users create plugins with C# easier. Download the MRP 2 Plugin template from this link. This template contains 2 references: MRP2.dll and MRP2Plugin.dll. These dlls can be found on MRP2.0.7.3.
The MRP2Plugin.dll is the core of the plugin. It contains an abstracted class called "Plugin". Our plugin will inherit this abstracted class and will implement specific methods. MRP2 will call these implemented methods and will be manipulated according to this methods.
MRP2.0.7.3 contains a directory called "Plugins". This directory contains all user created plugins. When MRP2 loads it goes through all of the files in the directory and tries to load them all.
Understanding MRP2.0.7.3 Plugins
What are MRP2Plugins? why MRP needs plugins?
MRP2 is a macro recording application. It repeats your most repeated tasks easily, but what happens when you need one or two things to be different on certain occasions? how can you make your script more dynamic? that is why MRP2 Plugins were created in the first place. It allows you - the users create a plugin that will manipulate your scripts on-the-fly to your requirements.
User plugins can manipulate typed keyboard events, mouse positions, mouse clicks and more...! User plugins are able to manipulate recorded events and/or played events. Changing an event input, preventing an event from playing, replacing an event and more!
Think of the possibilities. For example - PickyRecorder plugin allows you to filter out certain type of events (Mouse positions, keyboard input, etc...) by simply checking them. UltraScript allows you to play your script on any screen resolution by simply writing the original script recorded resolution. It simply does that by taking the original recorded resolution mouse coordinates and comparing them to the current resolution using percentage.
Use your imagination and you will be able to create a hell of a useful script plugins!
Setting up the environment
After you downloaded the MRP2PluginTemplate, extract it to any place you want. Then simply run the "MRP2PluginTemplate.csproj" file:
The MRP2Plugin template will be opened as previewed:
Exploring the Plugin class
The plugin class contains methods the user needs to implement in order to integrate with MRP2. We will go through the most important parts:
Open the "Plugin Information" region:
In this region you must fill your plugin most basic information: plugin version, author name (your name), description, HasSettings, and name. The HasSettings property tells MRP2 if this plugin contains any settings menu. if returns "true" MRP2 will enable the "Settings" button in the "Settings Manager":
As seen in the picture above - all of the "Plugin Information" region properties are displayed in the PluginsManager.
Open the "Plugin Events" region:
When our plugin starts loading - the "OnPluginLoad" method will be called. You can implement this method to perform any required actions to be performed when Mouse Recorder Pro loads the plugin (happens when MRP is loaded).
When our plugin is being closed the "OnPluginClose" method will be called. Again, any actions needed to occur when plugin closes needs to be implemented in this method. A plugin is being closed when MRP2 is being closed by the user.
When our plugin "Plugin settings" button is being pressed the "OnPluginSettings" method is being called. Implement this method to show a settings dialog as in "PickyRecorder", "UltraScript" and "VariableKeyboard" pre-loaded MRP2 scripts.
Open the "RecordingPlaying" region:
This region contains 2 separate regions: Record and play. This region contains methods that handle the script record/play event process methods. It also contains methods that handle the Script Record/Stop and Play/Stop methods.
The "Record" region:
OnRecordEventProcess - when the user is currently recording a script, input events are being generated. Whenever an input event is generated this method is being called. For example: the user click on the Left mouse button > an event is being processed > the "OnRecordEventProcess" method will be called. If this method will return true - the processed event will not be added to the script and will be consumed by the plugin. In this method the user can edit the processed event by simply modifying the "ev" parameter and returning "false" to let MRP finish processing the event.
The "ev" parameter is an object representing an MRP2 event, also called as "ScriptItem" object. The "ScriptItem" object is a simple structure:
EventType: mouse event, mouse position, key down, key up etc...
EventParamete: the event input (mouse coordinates, certain key, etc).
EventComment: a comment set by the user. By default a comment is null.
Going back to the other methods in the "Recording" region:
OnRecordStart - occurs when a script recorded started. Implement this method according to your needs.
OnRecordStop - occurs when a script recording stopped. Implement this method according to your needs.
The "Playing" region is exactly the same as the "Recording" region but this time you will manipulate a script played events and not recorded events.
We will not explain this region.
A "leftover" is the "OnPluginCreateToolStripMenuItem" method:
Implement this method only if you want to create a menu item under the "Tools > Plugins" menu. Return a "ToolStripMenuItem" object and MRP2 will automatically create that menu item for you! If you don't need a menu item for your plugin simply return null (as default in the template).
The "Plugin" class contains more useful objects like "Context" (use base.Context) to gain access to MRP2 application resources. We will not go through the "Context" object on this tutorial.
MyFirstPlugin - an example plugin!
Lets create our first example plugin. Simply download the the MRP2PluginTemplate.zip file as described under the article "Requirements" title. Extract the template and execute the "MRP2PluginTemplate.csproj" file. Now rename your project name to "MyFirstPlugin". Do the same for the Assembly name and Default namespace by right clicking on the project and selecting "Properties":
Now lets start coding!
We will create a very simple plugin that manipulates all of MRP2 recorded events. This plugin will replace any event with the "Type keyboard" event. The event input will be a simple text the user entered in the plugin settings window.
First thing first: Fill the required information in the "Plugin Information" region. Specify your name in the author property, plugin version, description, set "true" in the "HasSettings" property. Example:
Moving on - how do we manipulate all recorded events to be replaced with the "Type Keyboard" event? thats an easy one!
First we create a global string variable called "userInput" - this variable will contain the user "Type Keyboard" event input. The user can edit this variable in the plugin settings window.
After we created the "userInput" variable by declaring the following:
We can continue to the event manipulation method.
Go to the "Record" region under the "Recording/Playing" region. In the "OnRecordEventProcess" we write the following:
This will manipulate any recorded event (no matter what kind of event is this) to be a "Type Keyboard" event with a user custom input.
Now we will need to create the settings window.
In order to create the settings window we will need to create it. Right click on the "MyFirstPlugin" project > Add > New Item (or simply press the Ctrl + Shift + A). Now select "Windows Form", at the bottom "Name" type "SettingsDialog.cs" and click "Add":
This window will jump right when the user click on the "Plugin settings" button in the "Plugin manager".
Now in the "SettingsDialog.cs" designer drag a simple label, textbox and a button. Set the label text to: "Type keyboard input:" and set the textbox name to "UserInput_TextBox", set the modifiers of the textbox to "Public". Change the button name to "OK_Button" and set the button text to "Ok".
The window should look like this:
Now double click the button and add the following code:
Lets get back to our original plugin class. Double click on the "MyFirstPlugin.cs" and open the "PluginEvent" region. We will implement the "OnPluginSettings" method to show up the SettingsDialog we just created by adding the following code:
Now, how about creating a menu item under MRP2 plugins menu?
Lets create a simple menu called "MyFirstPlugin Settings" that opens up the settings of this plugin making it easier for the user to modify the plugin settings. Simply implement the "OnPluginCreateToolStripMenuItem" method in the following way:
As seen we created a ToolStripMenuitem object containing the menu item text and handled the menu click event. When we click on the menu item the plugin settings will be opened! (by calling the OnPluginSettings method we implemented).
When the "OnPluginCreateToolStripMenuItem" method returns a ToolStripMenuItem, MRP2 will automatically add that returned ToolStripMenuItem object to the "Plugins" menu.
Now simply right click on the solution > "Build Solution"! Go to your plugin source code destination folder > bin > Release. Copy your plugin "MyFirstPlugin.dll" to your MRP2 > Plugins directory. Simply run MRP2, go to Tools > Manage Plugins and select "MyFirstPlugin". Now click "Enable plugin":
Now simply click on "Plugin settings", set a text you want and click "Ok":
Now try to record a script - notice that when you move the mouse the "Mouse Position" event is not generated! a "Type Keyboard" with the text you put was generated instead:
Also notice that the menu item we generated also works:
Thats it! our simple plugin works! You can download the source code for this plugin right from here.
"UltraScript", "PickyRecorder" and "VariableKeyboard" plugins source code
You can download the pre-loaded plugins source code from the following link. UltraScript is the only plugin created under VB .net - those of you who wondered how to write plugins in VB .net can read the "UltraScript" source code.
Publish your plugins!
Post a comment with a link to your plugin download page at the end of this article and if it's good I will publish it with the next version of MRP2!
You can also mail me your plugin at: shynet@gmail.com .
Good luck!