« back to all changes in this revision
Viewing changes to source/plugins.rst
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Stephen Boddy
- Date: 2016-10-26 23:04:09 UTC
- Revision ID: stephen.j.boddy@gmail.com-20161026230409-zp8af5cdt3ar1903
Initial creation of GTK3 documentation tree for using with readthedocs.org
- files added:
- source
- source/imgs
added
removed
source/plugins.rst
1
.. image:: imgs/icon_plugins.png
2
:align: right
3
:alt: I have the POWWWWWWEEEEERRRRRRR!!!!!!
4
5
.. _plugins:
6
7
=======
8
Plugins
9
=======
10
11
Terminator can be expanded using plugins. Additional features can
12
be created outside of the main application, and added in at runtime.
13
14
In theory you should be able to implement fairly powerful plugins,
15
although so far the included ones we have are fairly small in scope.
16
17
The current plugins do not have configuration options in the
18
:ref:`prefs-plugins` tab of the :ref:`preferences`. The plugin
19
architecture was created before I (Steve Boddy) became maintainer,
20
and so far I haven't had reason to figure out the detail. I'm not
21
entirely sure if/how a plugin can add options to the configuration
22
options in the :ref:`prefs-plugins` tab. What plugins can definitely
23
do, because examples are below, is to:
24
25
- add menu items to :ref:`context-menu`,
26
- create their own windows,
27
- create handlers for strings that match a pattern.
28
29
.. note:: .. image:: imgs/plugins_links.png
30
:align: center
31
32
Several of the included plugins create :ref:`clickable-items` in
33
the terminal. These are made apparent by underlining the
34
item when the mouse hovers over it.
35
36
------------------------------
37
Included plugins
38
------------------------------
39
40
The following plugins are distributed by default with Terminator.
41
42
.. note:: Unless otherwise stated, the included plugins are under the
43
:ref:`licencing` as Terminator, GNU GPL v2.
44
45
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
46
Activity Watch
47
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
48
49
Original Author: Chris Jones
50
51
.. image:: imgs/activitywatch_notification.png
52
:align: right
53
54
Adds a menu item, **Watch for activity**, to :ref:`context-menu` which
55
will create a notification, as seen to the right, when there is output
56
to the terminal. This is useful when you have a long running command
57
and wish to know when it has completed, or output an update.
58
59
There is one option for this plugin:
60
61
**hush_period** (default: 10.0)
62
63
How long in seconds until the next notification of activity is
64
presented.
65
66
.. note:: There is currently no way to edit these options in the GUI,
67
it must be done directly in :ref:`config-file`.
68
69
An extract of this item being set would be::
70
71
[plugins]
72
[[ActivityWatch]]
73
hush_period = 30.0
74
75
Which would wait 30 seconds before showing another
76
notification of activity.
77
78
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
79
APT URL Handler
80
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
81
82
Original Author: Chris Jones
83
84
Text matching ``apt:.*`` will be converted into a click-able item that
85
when triggered with ``Ctrl``\ +\ ``click`` will launch the default
86
package manager for software on a debian system.
87
88
``right-click`` over the URL will add two entries to :ref:`context-menu`:
89
90
- *Open software manager* - Same as ``Ctrl``\ +\ ``click``
91
- *Copy package URI* - Just copies the URI to the clipboard
92
93
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
94
Custom Commands Menu
95
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
96
97
Original Author: Chris Jones
98
99
Adds a menu item, **Custom Commands**, to :ref:`context-menu` which
100
has a sub-menu containing its own **Preferences** item that launches
101
the window show below. Below that is a list of user configured
102
commands that can be chosen.
103
104
.. image:: imgs/custom_commands.png
105
:align: center
106
107
In this window you can create a **New** item, and **Edit** or
108
**Delete** existing ones. The selected item can be repositioned in
109
the sub-menu order using the **Top**, **Up**, **Down** and **Last**
110
buttons.
111
112
Clicking *New* or *Edit* gives the smaller window. An **Enabled**
113
item is shown in sub-menu, and a disabled one is not. The **Name** is
114
used for the sub-menu item text. The **Command** is the text that will
115
be entered into the current terminal with a ``Return`` at the end to
116
execute/enter it. You *do not* get a chance to edit the text first.
117
118
.. note:: If other terminals are receiving, they too will receive and
119
execute the *Command*.
120
121
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
122
Inactivity Watch
123
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124
125
Original Author: Chris Jones
126
127
.. image:: imgs/inactivitywatch_notification.png
128
:align: right
129
130
Adds a menu item, **Watch for silence**, to :ref:`context-menu` which
131
will create a notification, as seen to the right, when a terminal has
132
been quiet for a given period. This is useful when you have a long
133
running process that outputs constantly (i.e. compiling a kernel) and
134
you wish to know when it has ended. This notification will only show
135
once, unless there is some activity in the terminal after the initial
136
notification.
137
138
There are two options for this plugin:
139
140
**inactive_period** (default: 10.0)
141
142
How long in seconds until a terminal is considered inactive.
143
144
**watch_interval** (default: 5000)
145
146
How long in milliseconds between checks for inactivity.
147
148
Be aware that this combination will result in some uncertainty as to
149
the exact timing of the notification. In the worst case, with the
150
values given, the notification may take 14.9 seconds to appear.
151
152
.. note:: There is currently no way to edit these options in the GUI,
153
it must be done directly in :ref:`config-file`.
154
155
An extract of these items being set would be::
156
157
[plugins]
158
[[InactivityWatch]]
159
inactive_period = 30.0
160
watch_interval = 1000
161
162
Which would check every second if the terminal had been
163
silent for 30 seconds.
164
165
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
166
Launchpad Bug URL Handler
167
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
168
169
Original Author: Chris Jones
170
171
Text matching ``lp: #12345`` where 12345 is a bug number in launchpad,
172
will be converted into a click-able item that when triggered with
173
``Ctrl``\ +\ ``click`` will launch a browser to the bug report in
174
launchpad.
175
176
Additionally the plugin will accept variants where the prefix is in
177
capitals, i.e. ``LP``, and the ``:``\ , white-space, and ``#`` are
178
optional.
179
180
The item can also be more than one bug number, and each will be opened,
181
for example:
182
183
``lp: #12345. #67890, 54321,#9876``
184
185
``Ctrl``\ +\ ``click`` on this will open four pages; one for each bug
186
number.
187
188
``right-click`` over the URL will add two entries to :ref:`context-menu`:
189
190
- *Open Launchpad bug* - Same as ``Ctrl``\ +\ ``click``
191
- *Copy bug URL* - Just copies the URL to the clipboard
192
193
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
194
Launchpad Code URL Handler
195
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
196
197
Original Author: Chris Jones
198
199
Text matching ``lp:string`` will be converted into a click-able item
200
that when triggered with ``Ctrl``\ +\ ``click`` will launch a browser
201
to the page in launchpad, where string is one of the following:
202
203
- *project* - i.e. lp:terminator
204
- *project/series* - i.e. lp:terminator/gtk3
205
- *group/project/branch* - i.e. lp:~sparkstar/terminator/terminator
206
- *group/+junk/branch* - i.e. lp:~<yourname>/+junk/terminator
207
208
Additionally the plugin will accept variants where the prefix is in
209
capitals, i.e. ``LP``.
210
211
``right-click`` over the URL will add two entries to :ref:`context-menu`:
212
213
- *Open Launchpad branch* - Same as ``Ctrl``\ +\ ``click``
214
- *Copy branch URL* - Just copies the URL to the clipboard
215
216
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
217
Logger
218
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
219
220
Original Author: Sinan Nalkaya
221
222
Adds a menu item, **Start Logger**, to :ref:`context-menu` which will
223
popup a window for selecting a file name to save as. Any content then
224
written to the terminal will be written to the file too. Once started
225
the menu item will change to **Stop Logger** which does precisely what
226
you would expect.
227
228
.. warning:: There appears to be problems when applications switch
229
to/from alternate mode (i.e. vi, mc, etc.) The obvious
230
one is that the alternate screen is not "logged"
231
although it is not clear how this *could* be logged. The
232
second issue is that some of the output after the
233
alternate screen is not logged. See `LP#1477386`_ for
234
more info and progress.
235
236
.. _LP#1477386: https://bugs.launchpad.net/terminator/+bug/1477386
237
238
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
239
Maven Plugin URL Handler
240
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
241
242
Original Author: Julien Nicoulaud
243
244
Ummmm..... I'm not entirely sure what this will do, as I don't use
245
Maven. Updates on a postcard, please...
246
247
From the source:
248
249
Maven plugin handler. If the name of a Maven plugin is
250
detected, it is turned into a link to its documentation site.
251
If a Maven plugin goal is detected, the link points to the
252
particular goal page. Only Apache (org.apache.maven.plugins)
253
and Codehaus (org.codehaus.mojo) plugins are supported.
254
255
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
256
Terminal Shot
257
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
258
259
Original Author: Chris Jones
260
261
Adds a menu item, **Terminal screenshot**, to :ref:`context-menu`
262
that will take a screenshot of the underlying terminal, and present
263
a dialog for where to save it.
264
265
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
266
Test Plugin
267
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268
269
Original Author: Chris Jones (most likely)
270
271
An almost comically stripped down example.
272
273
------------------------------
274
Third party plugins
275
------------------------------
276
277
As I find (or I'm told about) plugins that are available elsewhere,
278
I'll add links here. I've done a preliminary search, and.. Wow! I
279
never knew there were so many out there.
280
281
If any of the authors would like to get their plugins added to the
282
main Terminator package, or they would prefer not to be listed here
283
for some reason, they can reach out to me through the project site
284
on Launchpad and we can sort it out.
285
286
I'm unsure of how these plugins are perceived. They are specific to
287
Terminator, but does that make them derivative in the eyes of GPL v2,
288
and therefore allow me to include them? If I want to include one in
289
the main package, do I have to hope the creator is still active?
290
Answers on a postcard...
291
292
.. warning:: I have done no testing or checking of these plugins. You
293
use at your own risk, and you are responsible for
294
evaluating the code for bugs, issues, and security.
295
296
In absolutely no order at all...
297
298
https://github.com/rail/dotfiles/blob/master/terminator_bugzilla_handler.py
299
- terminator_bugzilla_handler: Link "bug:12345" to the Mozilla bugzilla.
300
(As it is for Mozilla, it seems a bit misnamed.)
301
302
https://github.com/ilgarm/terminator_plugins
303
- clone_session: Split and clone ssh session
304
305
https://github.com/arnaudh/terminator-plugins
306
- open_any_file_plugin: Open any file with it's default application
307
308
https://github.com/dr1s/terminator-plugins
309
- cluster_connect: A way to connect to multiple machines as a cluster
310
311
https://github.com/mchelem/terminator-editor-plugin
312
- editor_plugin: Click on file\:line style links to launch a text editor
313
314
https://github.com/camillo/TerminatorPlugins
315
- LayoutManager: Saves and restores Layouts (which is built-in now, possibly redundant)
316
- TerminalExporter: Export contents to file
317
318
https://github.com/choffee/terminator-plugins
319
- searchplugin: Search Google for the selected text in a terminal
320
321
https://github.com/papajoker/editor_terminator
322
- editor_plugin: Another text editor launcher
323
324
https://github.com/papajoker/git_terminator
325
- git_plugin: adds commands for git when it detects a .git folder
326
327
https://github.com/iambibhas/terminator-plugins
328
- hastebin: Uploads selected text to Hastebin and opens browser on it
329
330
https://github.com/abourget/abourget-terminator
331
- TenscoresPlugin: Seems to be for launching set of tabs (which is built-in now, possibly redundant)
332
333
https://github.com/mikeadkison/terminator-google
334
- google: Another google-the-text plugin
335
336
https://github.com/mariolameiras/ssh-menu-terminator
337
- ssh_menu: I'm guessing a bit, but I think it works with SSH Menu ;-) the code is quite big to understand at a glance.
338
339
https://github.com/alesegdia/terminator-plugins
340
- Session: Save/load sessions (which is built-in now, possibly redundant)
341
342
https://github.com/Theer108/colorize
343
- colorize: Colour titlebar of each terminal separately
344
345
https://github.com/ju1ius/clisnips
346
- clisnips: Snippets for the command line.
347
348
https://github.com/GratefulTony/TerminatorHostWatch
349
- hostWatch: Attempts to figure out your current host, and apply a certain theme.
350
351
https://github.com/kmoppel/dumptofile
352
- dump_to_file: Dump console contents to a text file.
353
354
https://bitbucket.org/pgularski/terminator-plugins
355
- show_titlebar: Menu item to show/hide the titlebar.
356
- searchplugin: Yup, another Googler.
357
358
https://bitbucket.org/johnsanchezc/terminator-applauncher
359
- applauncher: A launcher/set-up tool (which is built-in now, possibly redundant)
360
361
https://www.snip2code.com/Snippet/58595/Terminator-plugin----log-the-output-of-t
362
- my_logger: Log the output to a file with a time-stamp as the name, and prefix each line with the time.
363
(Seems to be similar to, or derived from, the included one)
364
365
------------------------------
366
Installing a plugin
367
------------------------------
368
369
A plugin can be installed by adding the main python file (along with
370
any additional files) in one of two locations:
371
372
``/usr/[local/]share/terminator/terminatorlib/plugins/``
373
This will need root permissions to do. The optional ``local/`` is
374
usually for packages installed by hand, rather than through the
375
package manager, and this depends on how Terminator was installed
376
on your system.
377
``~/.config/terminator/plugins/``
378
This allows you to use plugins without needing root.
379
380
------------------------------
381
Creating your own plugins
382
------------------------------
383
384
.. note:: The following guide is initially sourced from a `tutorial`_
385
written by Chris Jones back in April 2010. I'm reproducing
386
it here as a precaution, although I don't expect the
387
original will disappear. It will get rewritten and expanded
388
as more knowledge and information is added.
389
390
.. _tutorial: http://www.tenshu.net/2010/04/writing-terminator-plugins.html
391
392
One of the features of the new 0.9x series of Terminator releases
393
that hasn't had a huge amount of announcement/discussion yet is the
394
plugin system. I've posted previously about the decisions that went
395
into the design of the plugin framework, but I figured now would be
396
a good time to look at how to actually take advantage of it.
397
398
While the plugin system is really generic, so far there are only two
399
points in the Terminator code that actually look for plugins - the
400
Terminal context menu and the default URL opening code. If you find
401
you'd like to write a plugin that interacts with a different part of
402
Terminator, please let me know, I'd love to see some clever uses of
403
plugins and I definitely want to expand the number of points that
404
plugins can hook into.
405
406
^^^^^^^^^^^^^^^^^^^^^^
407
The basics of a plugin
408
^^^^^^^^^^^^^^^^^^^^^^
409
410
A plugin is a class in a ``.py`` file in ``terminatorlib/plugins`` or
411
``~/.config/terminator/plugins``, but not all classes are automatically
412
treated as plugins. Terminator will examine each of the .py files it
413
finds for a list called ``available`` and it will load each of the
414
classes mentioned therein.
415
416
Additionally, it would be a good idea to import ``terminatorlib.plugin``
417
as that contains the base classes that other plugins should be derived
418
from.
419
420
A quick example:
421
422
.. code-block:: python
423
424
import terminatorlib.plugin as plugin
425
available = ['myfirstplugin']
426
class myfirstplugin(plugin.SomeBasePluginClass):
427
# etc.
428
429
430
So now let's move on to the simplest type of plugin currently available
431
in Terminator, a URL handler.
432
433
^^^^^^^^^^^^
434
URL Handlers
435
^^^^^^^^^^^^
436
437
This type of plugin adds new regular expressions to match text in the
438
terminal that should be handled as URLs. We ship an example of this
439
with Terminator, it's a handler that adds support for the commonly
440
used format for Launchpad. Ignoring the comments and the basics above,
441
this is ultimately all it is:
442
443
.. code-block:: python
444
445
class LaunchpadBugURLHandler(plugin.URLHandler):
446
capabilities = ['url_handler']
447
handler_name = 'launchpad_bug'
448
match = '\\b(lp|LP):?\s?#?[0-9]+(,\s*#?[0-9]+)*\\b'
449
450
def callback(self, url):
451
for item in re.findall(r'[0-9]+', url):
452
return('https://bugs.launchpad.net/bugs/%s' % item)
453
454
455
That's it! Let's break it down a little to see the important things
456
here:
457
458
- inherit from plugin.URLHandler if you want to handle URLs.
459
- include 'url_handler' in your capabilities list
460
- URL handlers must specify a unique handler_name (no enforcement of
461
uniqueness is performed by Terminator, so use some common sense with
462
the namespace)
463
464
- Terminator will call a method in your class called callback() and
465
pass it the text that was matched. You must return a valid URL
466
which will probably be based on this text.
467
468
469
And that's all there is to it really. Next time you start terminator
470
you should find the pattern you added gets handled as a URL!
471
472
^^^^^^^^^^^^^^^^^^
473
Context menu items
474
^^^^^^^^^^^^^^^^^^
475
476
This type of plugin is a little more involved, but not a huge amount
477
and as with URLHandler we ship an example in
478
``terminatorlib/plugins/custom_commands.py`` which is a plugin that
479
allows users to add custom commands to be sent to the terminal when
480
selected. This also brings a second aspect of making more complex
481
plugins - storing configuration. Terminator's shiny new configuration
482
system (based on the excellent ConfigObj) exposes some API for plugins
483
to use for loading and storing their configuration. The nuts and bolts
484
here are:
485
486
.. code-block:: python
487
488
import terminatorlib.plugin as plugin
489
from terminatorlib.config import Config
490
available = ['CustomCommandsMenu']
491
492
class CustomCommandsMenu(plugin.MenuItem):
493
capabilities = ['terminal_menu']
494
config = None
495
496
def __init__(self):
497
self.config = Config()
498
myconfig = self.config.plugin_get_config(self.__class__.__name__)
499
# Now extract valid data from sections{}
500
501
def callback(self, menuitems, menu, terminal):
502
menuitems.append(gtk.MenuItem('some jazz'))
503
504
This is a pretty simplified example, but it's sufficient to insert a
505
menu item that says "some jazz". I'm not going to go into the detail
506
of hooking up a handler to the 'activate' event of the MenuItem or
507
other PyGTK mechanics, but this gives you the basic detail. The method
508
that Terminator will call from your class is again "callback()" and
509
you get passed a list you should add your menu structure to, along
510
with references to the main menu object and the related Terminal. As
511
the plugin system expands and matures I'd like to be more formal about
512
the API that plugins should expect to be able to rely on, rather than
513
having them poke around inside classes like Config and Terminal.
514
Suggestions are welcome :)
515
516
Regarding the configuration storage API - the value returned by
517
Config.plugin_get_config() is just a dict, it's whatever is currently
518
configured for your plugin's name in the Terminator config file.
519
There's no validation of this data, so you should pay attention to it
520
containing valid data. You can then set whatever you want in this
521
dict and pass it to Config().plugin_set_config() with the name of
522
your class and then call Config().save() to flush this out to disk
523
(I recommend that you be quite liberal about calling save()).
524
525
^^^^^^^
526
Wrap up
527
^^^^^^^
528
529
Right now that's all there is to it. Please get in touch if you have
530
any suggestions or questions - I'd love to ship more plugins with
531
Terminator itself, and I can think of some great ideas. Probably the
532
most useful thing would be something to help customise Terminator for
533
heavy ssh users (see the earlier fork of Terminator called
534
'ssherminator')
Loggerhead is a web-based interface for Breezy
Version: 2.0.1