Brass Plugins: Mime Developers Guide
Now that you've got your application and a Mime
plugin to add gestures to it, we need to create the last piece of
the puzzle.
Writing the Descriptor
The Descriptor file is included
in the plugin workspace zip file
The descriptor file is what makes your plugin friendly to your
users. It describes the feature of your plugin, each action (function)
it provides and what the criteria are for the action to take place.
It is a plain text file, named the same as your DLL but suffixed
with .NFO instead.
Open your favourite text editor and create a new file. It's a good
idea to start with a comment as a reminder. Comments begin with
a semicolon as the first character of a line. Type the following
into your file:
; Descriptor file for TestPlugin. Created
on <date>, version <version>
The first actual (non-comment) line of a descriptor file must begin
with "DisplayName::", and provide a short (one or 2 word)
name for the plugin. This is the text that is shown to the user
in the Mime configuration dialog. In the screenshot below, the display
names are "Built In - All Apps" and "Internet Explorer".
For our test plugin we'll provide a simple display
name. Type this into your text file underneath the comment line:
DisplayName::My Test Application
The next line of the descriptor file must begin with
"FeatureSet::", and provide a few sentences describing
what this plugin is for. It should also explain the criteria in
plain English to the user. The text listed here is shown to the
user in the "Action Description" panel when they select
your plugin. Type the following into your text file, immediately
under the "DisplayName::" line:
FeatureSet::Gestures for my test application,
compatible with version 1. Criteria: gesture must be inside my
application.
The next line describes the type of descriptor. This
is how Mime distinguishes between scripted actions using the Custom
Action Wizard, and developed plugins in DLLs. Type following into
your text file, immediately under the "FeatureSet::" line:
Type::Plugin
That completes the compulsory lines. Now you can add
descriptors for each action (function) in the plugin DLL. In our
case we only added one action (ShowAboutBox), so we only need to
add one descriptor. The format of a descriptor is:
FunctionName::FunctionDisplayNameParameterDescription::Description
Type the following into your text file:
ShowAboutBox::Show About Box::0::Displays
the About dialog
The FunctionName must of course be the exact, case
sensitive function name of the action function in the plugin DLL.
Mime uses this string to locate the action function in the DLL -
if the string is wrong, Mime won't be able to find the function.
The FunctionDisplayName is just a visual enhancement.
Internally in your DLL you might want to name an action function
"ThisIsMyVeryLongActionFunctionXX". Not very user friendly,
so you might want to display a more friendly description to the
user. This field has absolutely no programmatical effect on Mime
or your plugin. This is perfectly legal syntax:
PostMessageNullWPARAMToMyApp::Display Help Screen::0::Displays
the help screen in my application
Here the function name is clearly descriptive to you as the coder,
but meaningless to the user. The "Display Help Screen"
string field is far more user-friendly.
If you're lazy and decide that your function names & descriptions
are clear enough, you can supply a "0" (zero) for this
field. Mime will then use the function name as the display name.
You can test this out after following the tutorial by changing the
descriptor line to:
ShowAboutBox::0::0::Displays the About
dialog
The action item in the gesture configuration page
will from "Show About Box" to "ShowAboutBox"
(the function name).
Remember that everything in this file is for the benefit
of the user. The better your descriptions and display names, the
easier it is for the user to use the plugin.
Save the text file as "TestPlugin.NFO" -
descriptors must be named the same as the DLL they describe, but
with an NFO suffix.
Telling Mime About Parameters
In the first ShowAboutBox descriptor line above you'll
notice a "0" (zero) in the third field. This field is
the "parameter" field - how you tell Mime if you want
a parameter or not. By specifying 0 here Mime will not allow the
user to give any parameter input for this action, and no parameter
will be passed to the action function.
If you want the user to specify a parameter (for example,
"Web page to load" parameter for the "LoadAPage"
action/function), you simply type the description of the parameter
here. This description has absolutely no code-related effect. Mime
sees that you provided a description rather than a "0"
and loads it into the configuration system. You can type "Purple
Monkey Dishwasher" here, and that's what Mime will prompt the
user for. Indeed.
The parameter description is included next to the
action in the "Available Actions" tree:
And the parameter box is enabled in the "Draw
Gesture" dialog. The string you supply is used in both cases:
When the user supplies a string for this action, Mime
handles the action-to-parameter-to-gesture association internally.
When the user makes the gesture, your action function receives the
user supplied parameter in the szParam function parameter.
For example, the screenshot above shows a parameter
for "GoToWebsite". The NFO descriptor line for this function
would look like this:
GoToWebsite::0:The website
address to go to when you make this gesture::Loads the web address
you specify in the parameter field.
Note the parameter field. The action function would
look like this:
extern "C"
__declspec(dllexport) void GoToWebsite(HWND hWnd, const char*
szParam)
{
if(strlen(szParam) == 0 || strcmp("0",
szParam)
{
// No parameter
was supplied by the user, abort
return;
}
// szParam == the website to load
ShellExecute(NULL, "open", szParam,
NULL, NULL);
}
This is all you have to do to accept parameters in
your action function. You can of course tell the user to give you
whatever input you like.
You've finished everything needed for a plugin! Now
it's time to test it...
|
