Write a Plugin
Version 1.2
Welcome to the DOMercury Plugin Tutorial.
Here I will explain in some detail
how to write a plugin to add your own desired functionality to DOMercury.
First I would suggest downloading the
DOMercury Plugin Template and some example plugins from the
Downloads page. A lot of the gruntwork is already done for you
then.
NOTE: I am not responsible for anything that may happen due to using someone's
plugin. I cannot control the intentions of other people out there and the best advise
I can give you is to use caution, and not install someone's "FormatMyCDrive" plugin.
DOMercury Plugin
Setup: Getting Started
A DOMercury plugin is a .NET Class Library compiled into a .dll and dropped into the Plugins folder where
DOMercury is installed.
DOMercury interfaces with your plugin through predefined interfaces, which your plugin must implement.
DOMercury discovers the plugin within your assembly through the use of an attribute placed
on top of the every class implementing at least one of the IItemProvider, IActionProvider,
IParamProvider and ISubIndex interfaces. Your project
will recognize these interfaces after you import the DOMercuryInterfaces dll.
Start a Plugin from a Scratch Project
Below is a set of steps you need to take to set up your Project to create a DOMercury
Plugin.
If you are using the DOMercuryPluginTemplate the following steps will have already
been performed for you.
1. Start a new Class Library Project.
2. Import the IDOMercuryInterfaces dll, located whereever you installed
DOMercury.
4. Put Using DOMercury.Interfaces; or Imports DOMercury.Interfaces at the top of
your code file.
5. Create a class with the name of your plugin which implements one of the provider
interfaces
6. Drop the following attribute on the line right above your class definition:
[DOMercuryPlugIn("Description of Plugin - Not really used anywhere")]
The above code does nothing more than tell DOMercrury "This class is a plugin interface",
however it is still required.
7. Start writing your plugin! Some commonly used index items are included
in the DOMercury.Items namespace, or you can use the DOMercury.Interfaces.IItem
interface to create your own.
Start a Plugin from the Plugin Template
If you are using the plugin template, the above steps are already done for you,
however you need to do a few things in order to make your plugin your own:
1. Double Click the Properties folder underneath the DOMercuryPluginTemplate
project.
2. Change the Assembly name: field to the desired name of your
plugin.
3. Click the Assembly Information button. Fill out the information
specific to you. If your plugin is going to be COM visible, you may want to
change the GUID.
4. Decide which provider interfaces you are going to use, then change the Name
and Description properties to return information specific
to your plugin.
There you should have it, you should be ready to start writing the meat and potatoes
functionality of your plugin. Awesome eh?
DOMercury Plugin
Framework: Interfaces and Attributes
DOMercury interfaces with your plugin via... surprise surprise: Interfaces.
Interfaces basically just define a series of methods that a class must follow.
These are useful because another class or program does not need to know the specifics
of any certain class, it just needs to know that if a class implements a specific
interface, the it will have the methods the other class or program is looking for.
In this way, DOMercury does not need to know that it is currently accessing the
HaltAndCatchFire plugin, it just knows it is seeing a class which implements the
IDOMercuryPlugin interface and can therefore call the DefaultItems property to grab
some items to stick into the index.
There are four interfaces included in the DOMercury.Interfaces namespace which are
Providers for IItems, IActions, Parameters, and sub indexes. The interfaces
are split to allow you to write all sorts of plugins, some which just provide more
items, some which could just provide more actions to currently provided items, some
to create sub indexes for item types, or all-encompassing plugins to add custom
items types with thier own actions. Because of the modular design of these
interfaces, you have the freedom to implement or ignore any functionality you want.
IItemProvider
This is the interface that allows your plugin to provide DOMercury with IItems,
it provides functionality for DOMercury to use to retrieve items to put into its
main index.
Members:
|
Name |
Returns |
Description |
|
Name |
string |
The Name of your plugin |
|
Description |
string |
A Description of your plugin |
|
HasOptions |
bool |
Tells DOMercury whether to enable to Show Options button. If you are not providing
options, set this method to false. |
|
ShowOptions |
void |
Called when the ShowOptions button is pressed. You should display your options
form here. |
|
Items |
List<IItem> |
Returns a list of IItems to populate the index with |
|
CustomIcons |
List<IconPair> |
Returns IconPairs containing the ItemType of your custom IItems and a bitmap to
be used as thier ItemType |
If you are providing custom IItems with thier own list of actions, you can
make use of the IItem interface to create your own versions of Items and use this
IItemProvider interface to provide them to DOMercury.
IItem
The IItem interface is the set of methods that every Item in the DOMercury index
must implement. To create your own Item, all you need to do is create a class
which implements the IItem interface and then have your plugin return instances
of that class throught the Items property of the IItemProvider.
Members:
|
Name |
Returns |
Description |
|
DisplayName |
string |
The Name of the item to show the user |
|
DisplayDesc |
string |
The description of the item to show the user |
|
ItemType |
string |
The type of this item, used to provide the possible actions. |
To provide your custom item with a list of actions to perform on it, you must create
an IActionProvider with an ItemType property that must match the IActionProvider
ItemType property. This way DOMercury
will know to give your custom item the actions you provide in the Actions property of your IActionProvider...
IActionProvider
This is the interface that allows your plugin to provide DOMercury with IActions
to use with specific ItemTypes, it provides functionality for DOMercury to use to
retrieve actions and display them when an IItem of the matching ItemType is selected.
Members:
|
Name |
Returns |
Description |
|
Name |
string |
The Name of your plugin |
|
Description |
string |
A Description of your plugin |
|
HasOptions |
bool |
Tells DOMercury whether to enable to Show Options button. If you are not providing
options, set this method to false. |
|
ShowOptions |
void |
Called when the ShowOptions button is pressed. You should display your options
form here. |
|
Actions |
List<IAction> |
Returns a list of IActions to populate the Action Pane when an IItem of ItemType
is selected. |
|
ItemType |
string |
Gives the ItemType for which DOMercury should provide these actions. |
If you are implementing this interface, you will have to create some actions using
the IAction Interface to provide DOMercury with...
IAction
While the IItem interface allows you to create custom items, the IAction interface
allows you to create custom Actions for either your custom items or for currently
existing items.
Members:
|
Name |
Returns |
Description |
|
ActionType |
string |
The Name of the action shown to the user |
|
Description |
string |
The description of the action to show the user |
|
ParamDescription |
string |
The description of the parameters needed, shown to the user |
|
ParameterType |
string |
The type of parameter the action takes. If none, use Unused |
|
Perform(IItem, object) |
bool |
The actual functionality of the action, takes in an IItem and an object to represent
the parameters. Returns a bool indicating success or failure. |
If you are providing a specific ParametersDataSource in your plugin, and this action is the
action that needs to utilize this datasource, you need to this
ParameterType
to the
ParameterType of your IParamProvider interface, described
below.
DOMercury also includes some built in
ParameterType strings you
can use for the
Parameter Pane autocomplete:
|
Name |
Description |
|
CommandLine |
Sets the Autocomplete source to the parameters history (Equivalent to Unused) |
|
Path |
Sets the autocomplete source to the File System Directories |
|
PathFiles |
Sets the autocomplete source to all Files and Folders in the System |
|
URL |
Sets the autocomplete source to previously used URLs in the System |
The core functionality of DOMercury is entirely centered around the
IAction.Perform()
function. A program which shows you some suggestions of things you might be
looking for yet gives you no means with which to do anything with is pretty useless.
The item pane and the action pane serve to give your action the item and parameters
it needs to perform, given in the IItem and object format.
Your action should know what specific type of IItem and paraemeters it is expecting
and cast them to the correct objects before perfroming the action. If your
action takes in an ItemsList and a CommandLine parameters, the first two lines of
your
Perform() function could look like this:
Itemslist temp = ((ItemsList)(item));
string prmtrs = ((string)(specialParams));
From there, you can write the code you need to perform your action. If your
ParameterType is a built in type (shown in the table above)
you can cast it to a string.
IParametersProvider
The IParametersProvider allows you to supply certain actions with a list of possible
parameters to choose from...
Members:
|
Name |
Returns |
Description |
|
Name |
string |
The Name of the IParametersProvider |
|
Description |
string |
The description of the IParametersProvider |
|
HasOptions |
bool |
Tells DOMercury whether to enable to Show Options button. If you are not providing
options, set this method to false. |
|
ShowOptions |
void |
Called when the ShowOptions button is pressed. You should display your options
form here. |
|
ParametersDataSource |
List<object> |
The list of parameters to provide the DOMercury Parameters Pane with when an action
with the ParameterType matching this provider's ParameterType is selected. |
|
ParametersDisplayMember |
string |
The DisplayMember to use to display the string representation of each parameter
object to the user. |
|
ParameterType |
string |
The type of Parameters being provided. Must match the ParameterType of the action
requesting this ParametersDataSource |
The ParametersDataSource is a List of objects because you should be able to make
the parameters object anything, just as long as you are able to give it a DisplayMember
string representation. If you just wish to use ToString as the DisplayMember,
return null or Nothing as the DisplayMember.
ISubIndex
The ISubIndex provides some powerful functionality to DOMercury. Depending
on the current item and action selected when the user initiates the sub index buttons
(Alt+RightArrow), an entirely new index of IItems can be provided.
Members:
|
Name |
Returns |
Description |
|
ParentItemType |
string |
The ItemType of the item which can become the parent item over this sub index |
|
EnableSearch |
bool |
If true, the sub index results will act like the standard index, if false, all results
will be displayed. |
|
HasOptions |
bool |
Tells DOMercury whether to enable to Show Options button. If you are not providing
options, set this method to false. |
|
ShowOptions |
void |
Called when the ShowOptions button is pressed. You should display your options
form here. |
|
Name |
string |
The Name of your plugin |
|
Description |
string |
A Description of your plugin |
|
GetSubIndex(IItem, IAction) |
List<IItem> |
Recieves the currently selected IItem and IAction and then generates a sub index
based on the parameters. |
NOTE: Obviously your subindex can only be accessed when the current item is of the
ParentItemType provided.
DOMercury Plugin
Framework: Existing Item Types
For those plugins who just want to add existing actions to current item types, all
default DOMercury items are included in the DOMercuryInterfaces library in the
DOMercury.Items namespace. This way, inside your IAction.Perform() function you
can cast the IItem to the specific type of item you need in order to complete the
action. Below is
the list of Provided Item types and details on them...
Alias
The Alias Represents the custom instructions that you can enter using the Alias Manager
tab in the Option form. The Alias class exists here for you if you wanted to create more
actions to use with the aliases by casint the IAction.Perform IItem to an Alias, however creating aliases programmatically is inadvisable
as they will
NOT show up in the Alias Manager.
CurrentWindowItem
This is another class that you have access to just so you can create actions for it.
The CurrentWindow is the window that had focus just before DOMercury was invoked.
SystemWindow
The SystemWindow Item represents a currently visible SystemWindow on your system (visible by the taskbar or system tray usually)
They are automatically created by DOMercury when programs are opened and removed when those programs are closed.
ItemsList
The ItemsList is basically a list of File System Paths. Its item type is ".*" if it contains multiple paths of
multiple file types. If the ItemsList contains just one PathItem, then its type is the file extension of that path. If the path
is a folder, the type is "folder". Technically it is a list of PathItems,
and can contain 1 to many PathItems.
For a good example on how ItemsLists are used in plugins, check out the DOMyDocumentsPlugin and the OutlookActionsPlugin examples.
PathItem
the PathItem is an IItem wrapper around a file path string, however it is not directly used by DOMercury. All PathItems need to be
encapsulated by an ItemsList
in order to work properly with DOMercury, even if you only want to work with one path. In fact
some of the ItemsList actions only perform thier action on the first item selected, and that should be displayed to the user.
StartMenuItem
This item represents a shortcut in the system and user StartMenus. Pretty simple actually.
TextItem
The TextItem is an IItem Wrapper around a string of text.
If you wish to see the specific methods of any of these items, you can always choose View->Object Browser in Visual Studio and
look at the DOMercury.Items
namespace under DOMercury.Interfaces.
DOMercury Plugins:
Providing Options
Many of you will undoubtedly be ambitious enough to create customizable plugins which could offer user options and save state
between instances of DOMercury. It would be logical then to be able to show the user an Options Form. This should be done within the ShowOptions() method in any of the providers, where you can create a form and call it with ShowDialog. If you have highly coupled providers, you may
want the ShowOptions() method from each to call the same options form. It is important to note however that the
Class Library Visual Studio project does not reference the System.Windows assembly by default, and you will have to do so if you wish to
show an options form. You can do this by right-clicking on the References folder underneath your project in the Solution Explorer and
choosing Add Reference... Under the .NET tab scroll down to System.Windows and choose OK. You can now add a Windows (or two) to your plugin.
Obviously providing options is not very useful unless you can save the options somewhere for later. How you do this however is up to you.
If you have done some digging around in the DOMercury install folder, you will have noticed that input history and aliases are saved to xml files.
XML files have been my preferred method of program settings due to File IO. your plugin can save to a MyPlugin.txt file or whatever you want, and
just have that file in sitting in the Plugins Folder next to your plugin. You could even save to a database if you wished, just remember that others may
want to use your plugin and IO from a MSSQL Database may not be possible for them. The same if you want your plugin to access the internet. An internet
enabled plugin has great potential to do some sweet stuff, just make sure it isn't going to crash if the PC doesn't have an internet connection at the time.
If DOMercury catches a plugin that bubbled up to it from a plugin, it will display the error to the user.
Well, I think that about sums up writing a DOMercury plugin, if I have forgotten anything let me know either through email or through the Forums. Thanks and happy
coding.