FileRenamer v2 Documentation
Contents
- General Information
- Plugging Rules
- Plugin Information
- Plugin Settings
- Interaction: Running a Plugin
- An Example Plugin
1. General Information
When you are going to make a plugin, and thus are reading this, I assume you know how to make one.
So here I am not going to explain that, I will just tell you how the plugin should interact with FileRenamer.
Since b25, FileRenamer supports plugins. Plugin support is not likely to change in future versions,
so if it works for the first version, it will probably work for other versions too.
Should something about plugin support change however, I will document the changes here.
Plugins are dll files, that is what FileRenamer will look for.
Say the filename (without extention) of the plugin is Plugin_Name, then
it should be put in app.path\Plugins\Plugin_Name\Plugin_Name.dll
(app.path is the directory where the FileRenamer executable is located).
When loading all plugins an putting them in a list, FileRenamer will start the plugin only to get the PluginName,
so make sure you don't put anything in the startup function that might require user interaction, or may slow down loading the plugins
About this documentation: it is written for Visual Basic 6. But I am sure that with other programming languages you can still figure out
quite well how to make a plugin. The example plugin is written in VB6, but I think (I don't know many other programming languages)
that it'll be pretty easy to convert that.
2. Plugging Rules
I have made plugging rules for two reasons: To make sure the users don't get annoyed by what you do,
and because FileRenamer requires certain variables or subs/functions to exist, because it will
address them.
First for userfriendliness:
- Don't use a splash screen, it might look nice, but a splash screen for every plugin that is loaded is annoying, if you have many.
Then a plugin is unloaded after every action. So when it's put in a list it is loaded, when a user wants information it is loaded,
When a user changes settings it is loaded, and finally when a plugin is run it is loaded. All these actions would generate splash screens.
I hope you agree that's very annoying.
- Use a clear name, and a good description of what the plugin does. And make sure it does what the description says.
Then for the good interaction:
- The plugin should be a dll, located in app.path/Plugins/Plugin_Name/Plugin_Name.dll, as told in chapter 1.
- The project name for the plugin should be the same as the filename, the real name can be defined in the PluginName variable.
- The main classname should always be clsPlugin, because this is the class FileRenamer will load.
- The plugin should have at least one public variable: PluginName, which must be initiated at startup, containing the name of the plugin
(not the filename, the filename doesn't have to be that accurate (you can keep it short) as long as this name is).
- There should be a public function Init (more about this in chapter 5), a public sub Settings (more about this in chapter 4)
and a public sub Information (more about this in chapter 3), FileRenamer will call these function/subs.
3. Plugin Information
As said in the rules, there must be a public sub Information().
This sub is called when a user presses the plugin information button. It will be called without arguments, so
the sub can be like this:
Public Sub Information()
End Sub
Actually this code will do, or without the comment. But I do request you to at least put some code in it for an informationscreen
with information. The sub Information() is required, but it doesn't have to do anything for the plugin to work properly.
It is just a request from me to inform the users of what the plugin do, even using a msgbox will do.
Tough designing a form with a nice logo on it is good too, of course :)
4. Plugin Settings
Perhaps your plugin works without any settings, but perhaps you like to have the user to be able to choose some preferences.
In that case there is the sub Settings(). This sub is required too, but if you want to keep it empty, good too.
If there are no settings, and your plugin works in only one way; its own way, then there doesn't have to be a settings screen.
If there is no settings screen, you could use a msgbox with 'No settings available', but I think the user will understand that there
are no settings when nothing pops up too.
The Settings sub will also be called without arguments, so it can look like this:
Public Sub Settings()
End Sub
Saving settings is another thing. When the settings screen is opened, the user can change some settings.
When he closes the screen, the settings are lost. So you have to make sure they are saved to a file or something.
I have made FileRenamer to not use the registry at all, it would be nice to keep it that way, but if you want your
plugin to use the registry for saving settings, go ahead. Just saving them in some textfile will probably do too.
That's what FileRenamer does.
So before closing the Settings Screen the settings must be saved, and before running the plugin, the settings must be loaded.
5. Interaction: Running a Plugin
Now on to the part a plugin is made for, running it. First I will explain how FileRenamer calls on plugins.
When a user clicks run plugin, it first checks if a plugin is selected. If it is, the plugin will be started.
Then it starts like it always does, refresh the filelist and start a loop to go by each file in the
filelist. Then, for each file, the plugin will be called with the Init() function.
This time three arguments will be given along with the function call:
FileName: the filename without the path or extension,
PathName: The entire path to the file, always with the last "\", no matter if it's in root or not,
Extension: the extension of the filename.
The Init() function is also required, and putting nothing in it is rather lame, then the plugin will do nothing. I guess you understand that.
Furthermore, the Init() function should return a string, which is the full filename, so including path and extension of the renamed file.
if you don't want to change the path, then leave it unchanged, same with the extension, or the filename itself.
This way, the Init() function should look somewhat like this:
Public Function Init(ByVal FileName As String, ByVal FilePath As String, ByVal Extension As String) As String
Init = Result
End Sub
When starting a plugin, first load the settings, if there are any (this was discussed in chapter 4). Then do with these strings
what you want. And finally return the full filename, with path and extension.
That is one option, but perhaps you want your plugin to do something else, and not have FileRenamer changing any filenames.
In that case, just return an empty string, and FileRenamer will do nothing.
6. An Example Plugin
The plugin I am creating is called Example, this means:
- It is located app.path\Plugins\Example\Example.dll.
- The project name is Example
- The main classname is clsPlugin (this is not a result of the name of my plugin though, it just always is)
The purpose of the plugin is to make an example plugin, so I make the name that will be shown in FileRenamer 'An Example Plugin'.
The plugin has no settings, so no settingsscreen will be loaded. It does show a msgbox with the information that it is an example plugin.
And when run it does nothing, so just returns an empty string.
What I have made here is the minimum for a plugin, what's in here should at least be in your plugin too.
This is the code of my plugin:
Option Explicit
Public PluginName As String
Private Sub Class_Initialize()
PluginName = "An Example Plugin"
End Sub
Public Function Init(ByVal FileName As String, ByVal FilePath As String, ByVal Extension As String) As String
Init = ""
End Function
Public Sub Information()
MsgBox "This is a plugin that serves as an example for pluginmakers."
End Sub
Public Sub Settings()
End Sub