Plugin

From EventGhost
Jump to: navigation, search

A plugin is a file (or group of files) you can install into EventGhost to add new behaviour, and customize EventGhost to meet your needs.

Plugins typically provide new events to act on, and/or new actions to perform.

Built-In Plugins

EventGhost has several "plugins" built into it. These are always active, even though they don't appear in the Add Plugin dialog (see below) nor the Autostart.pngAutostart tree entry. These are Plugin.pngEventGhost, Plugin.pngSystem, Plugin.pngWindow, and Plugin.pngMouse.

Included Plugins

EventGhost ships with dozens of additional plugins, to provide useful features such as acting on keystrokes (Plugin.pngKeyboard) or showing test patterns (Plugin.pngTest Pattern). Play around with them and see what you can find!

Activating and Configuring Plugins

To activate a plugin so you can use it, click the Add Plugin (Plugin.png) button on the toolbar, or or click the Configuration menu and select "Add Plugin..." You will be presented with a dialog box listing all the plugins available to you. When you click on a plugin, it will show some brief documentation in the right side of the dialog. Click OK, and the plugin will be installed under Autostart.pngAutostart in your configuration tree.

Some plugins require additional configuration in order to function. For example, Plugin.pngDirectory Watcher needs to be told what directory to watch. When you try to activate such a plugin, you will be presented with a configuration dialog requesting the required information. If you click Cancel, the plugin won't be installed.

You can reconfigure a configurable plugin at any time by double-clicking the plugin's entry in the configuration tree.

Using Plugins

In general, you will want to read an individual plugin's documentation in order to learn how it is used. If you don't, you may miss out on some of the special features it offers.

Many plugins make new actions available for you to use. You will find these in the Add Action dialog the next time you go to add an action to a macro.

Many plugins generate new events that you can use to trigger your macros. Unlike with actions, there is no dialog or list of all available events. You will need to read the plugin's documentation. You may make some progress by disabling the "Log only assigned and activated events" checkbox, and watching the EventGhost log pane for interesting events.

Disabling Plugins

You can right-click on a plugin, and select "Disable Item", to disable the plugin. The plugin is still loaded, but should not be active.

You can enable and disable events using any of these actions: Action.pngDisable Item, Action.pngEnable Item, Action.pngEnable Item Exclusively. This can be useful for changing EventGhost's behaviour based on specific events.

Third-Party Plugins

Although EventGhost comes with many useful plugins, there are some events or actions that are not covered by the included plugins. Fortunately, anybody with Python programming knowledge can create new plugins for EventGhost, and many people have.

Finding Plugins

  • The page Plugins lists many plugins which are known to be useful.
  • The Plugin Support page of the EventGhost forums has many plugins, though it may take some digging to find the one you need.
  • Some software developers develop their own plugins to make their software integrate with EventGhost. (See for example the plugin for AutoRemote.)
  • You will probably find interesting plugins if you search GitHub and other similar source code repositories.
  • If all else fails, you can always search the internet!

Installing Plugins

There are (at least) three different ways that an EventGhost plugin can be distributed. The instructions on installing them are given below.

In all cases, once the plugin is correctly installed, then you should be able to activate it and use it just like described above.

.egplugin file

As of EventGhost 0.5.0, there is a custom file format with the .egplugin file extension. If EventGhost is installed properly, you can simply download a .egplugin file, and double-click on it in Windows in order to install it in EventGhost.

Plugins installed in this manner go into your Program Data folder. You can see this folder in Windows by opening a new File Explorer window, and typing %ProgramData%\EventGhost\plugins into the location bar.

If you are using an older version of EventGhost, you can rename the file so it has a .zip file extension, and then proceed to the next section to install the plugin.

.zip file

A plugin may be distributed in a .zip file for easy distribution, particularly if it contains several files. Open the .zip file using your favourite program (modern versions of Windows have built-in support for .zip files; you may also find 7-Zip useful), and look for the plugin's folder. This will usually be a folder with the same name as the plugin, and there should be a file named __init__.py inside it.

If you find such a folder, copy the whole folder into your Program Data folder as described above (ie. %ProgramData%\EventGhost\plugins\ ; create this folder if it does not already exist). You may see the folders of other plugins there; be careful that you do not accidentally put the folder inside one of these plugin folders! Also be careful that you don't overwrite any existing plugin with the same name.

If you do not see such a folder, but you do see a file named __init__.py in the zip file, proceed to the next section.

__init__.py file

Some plugins, especially those you might find in the EventGhost plugin forum, are distributed as a single Python source code file named __init__.py. Also, as noted above, some .zip files may contain __init__.py at their root.

Create a new folder for this plugin in your Program Data folder as described above (ie. %ProgramData%\\EventGhost\plugins\New plugin I found ; create the parent folders if they do not already exist). Copy __init__.py (and any other provided files that are needed; see the developer's instructions) into this new folder.

Writing Plugins

Although this is not difficult, there is a lot of information. There will eventually be a whole area of this wiki devoted to authoring plugins.

See Also