MysticThumbs example plugin
Add new image formats to MysticThumbs
How to use
Use this example project as a template to make your own.
Both Visual Studio 2008 and Visual Studio 2010 projects are both supplied for convenience.
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 requirementes. 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 saveform, 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 preview 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 both x86 and x64 platforms. The example project already has
the required projects set up.
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 both these 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 this example plugin:
- Build both 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 task manager.
- Provided the plugin loaded you should see the test pattern display for your
test.mtp file that looks like this:
You now have all the MysticThumbs thumbnail options available for your file format!
MysticCoder