Plugins
Add new image formats to MysticThumbs
Download example plugin here (Visual Studio 2008 and 2010 projects included)
Note: The VS projects are quite old now but can easily be imported into a newer version of Visual Studio and upgraded for use.
How to use
Use this example project as a template to make your own.
Visual Studio 2008/2010 projects are supplied for convenience. Newer versions can easily upgrade the project.
Visual Studio Express for Desktop is available FREE from Microsoft here.
Make one plugin project for each file type. If you require different file types
create new plugins for each. You register each file format extension necessary for
the file format, so you can for example register multiple extensions such as JPEG
has with .jpg, .jpeg etc.
The core interface that must be implemented is the IMysticThumbsPlugin interface.
In this example the class CExamplePlugin implements this.
MysticThumbs can request any number of these objects so it is very important that
you do not use any static variables that could cause conflicts amongst concurrent
running objects. Encapsulate everything in your class.
The documentation and comments in the MysticThumbsPlugin.h header file specify all
the required information that you will need to successfully implement your own plugin.
For the purposes of the example, we use the .mtp extension (which is actually the
plugin extension for MysticThumbs plugins) and generate a test pattern image dynamically
of the requested thumbnail size.
IMysticThumbsPlugin::GenerateImage method
This is the meat of the plugin.
In a typical plugin you will read from the passed
IStream interface pointer that
points to the head of the file being thumbnailed. This method parses the file and
generates the thumbnail and returns the image data
un-scaled. It
is not usually necessary to scale your image, and you can simply read and pass the
full image back, this will yield the fastest and best results. MysticThumbs and
Explorer will take care of scaling appropriate to control panel and operating system
requirements. The desiredSize and flags parameters are merely hints should you
require them.
If however, you are generating a thumbnail of an abstract nature, say for example
a sound waveform similar to the existing .wav format produces, then your image could be of any arbitary size, and the desiredSize
parameter can be used to determine the best size to render to.
The
desiredSize parameter represents the size of the thumbnail
that Explorer is requesting at the time, this could be for example 32, 48, 96, 256
or even very large if requesting for QuickView purposes. It is the
width
in pixels of the requested thumbnail.
The
flags parameter gives you hints as to what the control panel
settings are for your file extension, such as transparency, embedded thumbnail and
scaling settings. This may be expanded upon in future releases.
Building
Ensure you build for x86 and x64 platforms. The example project already has the required projects set up and ready to modify.
The x86 plugin should end with 32.mtp and the x64 plugin should end with 64.mtp,
for example ExamplePlugin32.mtp and ExamplePlugin64.mtp.
Place the plugin output files in a plugins folder in the MysticThumbs install directory,
eg. "C:\Program Files\MysticCoder\MysticThumbs\plugins\ExamplePlugin32.mtp"
Restart Explorer and they will be automatically loaded by MysticThumbs.
Register the plugin in the MysticThumbs control panel. Use the "Plugins"
button, where you can register and unregister plugins. Register will install the
required Explorer hooks for the file extensions assigned to the plugin and Unregister
will remove the hooks.
Using
If the plugin loads successfully you will find it in the MysticThumbs control panel
under an entry corresponding to the name you return in the method IMysticThumbsPlugin::GetName().
You can now use it just as you would any other natively supported file format with
all the benefits of the control panel options.
To test the example plugin
- Build Win32 and x64 Release configurations and place the resulting .mtp files in the MysticThumbs plugin folder.
- Create a dummy, empty file on your desktop called test.mtp
- Restart Explorer, for example using the MysticThumbs tray icon or task manager.
- Provided the plugin loaded you should see the test pattern display for your test.mtp file that looks like this:
Now modify the test project to suit your needs and file formats and see your images with all the MysticThumbs thumbnail configuration
options available for your file format.