Plugins¶

Activity Watch¶

Original Author: Chris Jones

Adds a menu item, Watch for activity, to The Context Menu which will create a notification, as seen to the right, when there is output to the terminal. This is useful when you have a long running command and wish to know when it has completed, or output an update.

There is one option for this plugin:

hush_period (default: 10.0)

How long in seconds until the next notification of activity is presented.

[plugins]
  [[ActivityWatch]]
    hush_period = 30.0

APT URL Handler¶

Original Author: Chris Jones

Text matching apt:.* will be converted into a click-able item that when triggered with Ctrl+click will launch the default package manager for software on a debian system.

right-click over the URL will add two entries to The Context Menu:

• Open software manager - Same as Ctrl+click
• Copy package URI - Just copies the URI to the clipboard

Custom Commands Menu¶

Original Author: Chris Jones

Adds a menu item, Custom Commands, to The Context Menu which has a sub-menu containing its own Preferences item that launches the window show below. Below that is a list of user configured commands that can be chosen.

In this window you can create a New item, and Edit or Delete existing ones. The selected item can be repositioned in the sub-menu order using the Top, Up, Down and Last buttons.

Clicking New or Edit gives the smaller window. An Enabled item is shown in sub-menu, and a disabled one is not. The Name is used for the sub-menu item text. The Command is the text that will be entered into the current terminal with a Return at the end to execute/enter it. You do not get a chance to edit the text first.

Inactivity Watch¶

Original Author: Chris Jones

Adds a menu item, Watch for silence, to The Context Menu which will create a notification, as seen to the right, when a terminal has been quiet for a given period. This is useful when you have a long running process that outputs constantly (i.e. compiling a kernel) and you wish to know when it has ended. This notification will only show once, unless there is some activity in the terminal after the initial notification.

There are two options for this plugin:

inactive_period (default: 10.0)

How long in seconds until a terminal is considered inactive.

watch_interval (default: 5000)

How long in milliseconds between checks for inactivity.

Be aware that this combination will result in some uncertainty as to the exact timing of the notification. In the worst case, with the values given, the notification may take 14.9 seconds to appear.

[plugins]
  [[InactivityWatch]]
    inactive_period = 30.0
    watch_interval = 1000

Launchpad Bug URL Handler¶

Original Author: Chris Jones

Text matching lp: #12345 where 12345 is a bug number in launchpad, will be converted into a click-able item that when triggered with Ctrl+click will launch a browser to the bug report in launchpad.

Additionally the plugin will accept variants where the prefix is in capitals, i.e. LP, and the :, white-space, and # are optional.

The item can also be more than one bug number, and each will be opened, for example:

lp: #12345. #67890, 54321,#9876

Ctrl+click on this will open four pages; one for each bug number.

right-click over the URL will add two entries to The Context Menu:

• Open Launchpad bug - Same as Ctrl+click
• Copy bug URL - Just copies the URL to the clipboard

Launchpad Code URL Handler¶

Original Author: Chris Jones

Text matching lp:string will be converted into a click-able item that when triggered with Ctrl+click will launch a browser to the page in launchpad, where string is one of the following:

• project - i.e. lp:terminator
• project/series - i.e. lp:terminator/gtk3
• group/project/branch - i.e. lp:~sparkstar/terminator/terminator
• group/+junk/branch - i.e. lp:~<yourname>/+junk/terminator

Additionally the plugin will accept variants where the prefix is in capitals, i.e. LP.

right-click over the URL will add two entries to The Context Menu:

• Open Launchpad branch - Same as Ctrl+click
• Copy branch URL - Just copies the URL to the clipboard

Logger¶

Original Author: Sinan Nalkaya

Adds a menu item, Start Logger, to The Context Menu which will popup a window for selecting a file name to save as. Any content then written to the terminal will be written to the file too. Once started the menu item will change to Stop Logger which does precisely what you would expect.

Maven Plugin URL Handler¶

Original Author: Julien Nicoulaud

Ummmm..... I’m not entirely sure what this will do, as I don’t use Maven. Updates on a postcard, please...

From the source:

Maven plugin handler. If the name of a Maven plugin is detected, it is turned into a link to its documentation site. If a Maven plugin goal is detected, the link points to the particular goal page. Only Apache (org.apache.maven.plugins) and Codehaus (org.codehaus.mojo) plugins are supported.

Terminal Shot¶

Original Author: Chris Jones

Adds a menu item, Terminal screenshot, to The Context Menu that will take a screenshot of the underlying terminal, and present a dialog for where to save it.

Test Plugin¶

Original Author: Chris Jones (most likely)

An almost comically stripped down example.

The basics of a plugin¶

A plugin is a class in a .py file in terminatorlib/plugins or ~/.config/terminator/plugins, but not all classes are automatically treated as plugins. Terminator will examine each of the .py files it finds for a list called available and it will load each of the classes mentioned therein.

Additionally, it would be a good idea to import terminatorlib.plugin as that contains the base classes that other plugins should be derived from.

A quick example:

import terminatorlib.plugin as plugin
available = ['myfirstplugin']
class myfirstplugin(plugin.SomeBasePluginClass):
  # etc.

So now let’s move on to the simplest type of plugin currently available in Terminator, a URL handler.

URL Handlers¶

This type of plugin adds new regular expressions to match text in the terminal that should be handled as URLs. We ship an example of this with Terminator, it’s a handler that adds support for the commonly used format for Launchpad. Ignoring the comments and the basics above, this is ultimately all it is:

class LaunchpadBugURLHandler(plugin.URLHandler):
  capabilities = ['url_handler']
  handler_name = 'launchpad_bug'
  match = '\\b(lp|LP):?\s?#?[0-9]+(,\s*#?[0-9]+)*\\b'

  def callback(self, url):
    for item in re.findall(r'[0-9]+', url):
      return('https://bugs.launchpad.net/bugs/%s' % item)

That’s it! Let’s break it down a little to see the important things here:

• inherit from plugin.URLHandler if you want to handle URLs.
• include ‘url_handler’ in your capabilities list
• URL handlers must specify a unique handler_name (no enforcement of uniqueness is performed by Terminator, so use some common sense with the namespace)
• Terminator will call a method in your class called callback() and pass it the text that was matched. You must return a valid URL which will probably be based on this text.

And that’s all there is to it really. Next time you start terminator you should find the pattern you added gets handled as a URL!

Context menu items¶

This type of plugin is a little more involved, but not a huge amount and as with URLHandler we ship an example in terminatorlib/plugins/custom_commands.py which is a plugin that allows users to add custom commands to be sent to the terminal when selected. This also brings a second aspect of making more complex plugins - storing configuration. Terminator’s shiny new configuration system (based on the excellent ConfigObj) exposes some API for plugins to use for loading and storing their configuration. The nuts and bolts here are:

import terminatorlib.plugin as plugin
from terminatorlib.config import Config
available = ['CustomCommandsMenu']

class CustomCommandsMenu(plugin.MenuItem):
  capabilities = ['terminal_menu']
  config = None

  def __init__(self):
    self.config = Config()
    myconfig = self.config.plugin_get_config(self.__class__.__name__)
    # Now extract valid data from sections{}

  def callback(self, menuitems, menu, terminal):
    menuitems.append(gtk.MenuItem('some jazz'))

This is a pretty simplified example, but it’s sufficient to insert a menu item that says “some jazz”. I’m not going to go into the detail of hooking up a handler to the ‘activate’ event of the MenuItem or other PyGTK mechanics, but this gives you the basic detail. The method that Terminator will call from your class is again “callback()” and you get passed a list you should add your menu structure to, along with references to the main menu object and the related Terminal. As the plugin system expands and matures I’d like to be more formal about the API that plugins should expect to be able to rely on, rather than having them poke around inside classes like Config and Terminal. Suggestions are welcome :)

Regarding the configuration storage API - the value returned by Config.plugin_get_config() is just a dict, it’s whatever is currently configured for your plugin’s name in the Terminator config file. There’s no validation of this data, so you should pay attention to it containing valid data. You can then set whatever you want in this dict and pass it to Config().plugin_set_config() with the name of your class and then call Config().save() to flush this out to disk (I recommend that you be quite liberal about calling save()).

Wrap up¶

Right now that’s all there is to it. Please get in touch if you have any suggestions or questions - I’d love to ship more plugins with Terminator itself, and I can think of some great ideas. Probably the most useful thing would be something to help customise Terminator for heavy ssh users (see the earlier fork of Terminator called ‘ssherminator’)