Cheat Sheets

Recent Posts

Writing Liferea Plugins Tutorial Part 3

Welcome to a new installment of the plugins tutorial! Todays issue will cover menu modifications. This allows you to add new menu options for features you introduce with your plugin.

GTK menu concepts

Before diving into the example code we need to cover some theory. GTK3 provides several APIs to build menus but for Liferea plugins only one of them is exposed: the GtkUIManager.

In short the GtkUIManager allows adding UI elements (menus ,toolbars, accelerators) using XML like this:
    <menu name="FileMenu" action="FileMenuAction">
      <menuitem name="New" action="New2Action" />
The above snippet defines an menu item that you can merged into the UI by calling a method like gtk_ui_manager_add_ui_from_string().

Note that above definition only says that there ought to be a menu action with internal action name "New2Action". So we still have to define this active and bind a callback.

Extending a menu in PyGI

Now how do we extend a Liferea menu? First we get the GtkUIManager:
self._ui_manager ="ui-manager")
Now we can add an XML snippet describing a menu
         <menubar name='MainwindowMenubar'>
           <menu action='ToolsMenu'>
             <menuitem action='MyPluginMenuEntry'/>
Please note that the GtkUIManager property is only exposed starting with Liferea version 1.12.2!

And as said above we need to add an action for this menu item. As actions can only be added in groups using a GtkActionGroup we need to create one first, insert the action and finally tell the GtkUIManager about the action group:
self._action = Gtk.Action('MyPluginMenuEntry', 'Awesome Function', 'Run a really awesome function', None)
self._action.connect("activate", self._do_action)

self._actiongroup = Gtk.ActionGroup("MyPluginActions") self._actiongroup.add_action(self._action)


Available Menus

You probably noticed the "ToolsMenu" and "MainwindowMenubar" ids in the XML snippet above. Here is a list of all menu ids in 1.12 which also can be found in src/ui/liferea_shell.c.
Name Description
FeedMenuAll actions regarding subscriptions and the feed list
ItemMenuAll actions regarding the item list
ViewMenuAll actions controlling reading layout
ToolsMenuThe menu to access preferences and update status
SearchMenuAll actions for finding stuff
HelpMenuThe place to go for help

Complete Solution

Everything put together in a plugin could look like this:
import gi

gi.require_version('Gtk', '3.0')

from gi.repository import GObject, Liferea, Gtk

class AppActivatable(GObject.Object, Liferea.ShellActivatable): __gtype_name__ = "MyPluginAppActivatable"

shell =

def __init__(self): GObject.Object.__init__(self)

def do_activate(self): self._action = Gtk.Action('MyPluginMenuEntry', 'Awesome Function', 'Run a really awesome function', None) self._action.connect("activate", self._do_action)

self._actiongroup = Gtk.ActionGroup("MyPluginActions") self._actiongroup.add_action(self._action)

self._ui_manager ="ui-manager") self._ui_manager.insert_action_group(self._actiongroup) self._ui_manager.add_ui_from_string( """<ui> <menubar name='MainwindowMenubar'> <menu action='ToolsMenu'> <menuitem action='MyPluginMenuEntry'/> </menu> </menubar> </ui>""" )

def _do_action(self, action, data=None): print("Action triggered")
For a real world example have a look at


Also check out the previous plugin tutorial posts

Liferea 1.12.1 Released

This is a bugfix release for the recent 1.12.0 release. Thanks to Leiaz tackling several complicated issues. Most prominent is a hopefully solved issue with the pane sizing with maximized window. Last but not least we have Italian and Indonesian translation updates.


* Fixes #562: Lintian spelling errors
  (reported by Paul Gevers)
* Fixes #563: Appstream data has new format
  (patch by Paul Gevers)
* Fixes #572: Doesn't remember some sort orders
  (reported by geplus)
* Fixes #504: Fix assertions/crashes on changing view layouts
* Fixes #573: Workaround to avoid GtkPaned shrinking

* #566: Update of Italian translation (Gianvito Cavasoli) * #566: Update of Italian default feed list (Gianvito Cavasoli) * #514: Update of Indonesian translation (Samsul Ma'arif) * #514: Added Indonesian default feed list (Samsul Ma'arif) * Update of German translation

Thanks for the stars!

Finally I wanted to say thank to all of you who starred the github repo after the 1.12.0 release! It really makes a difference to know how many people are out there caring.


Get a tarball or checkout the code from Github!

Liferea 1.12.0 Released

This is the first release of the new stable release line 1.12. Many thanks to all the contributors and package maintainers that made this possible!

Important changes compared to 1.10

    * Wide view is now default view
    * HTML view now has a 'View Image' context menu
    * Redesign of the wide view: large icons with teaser text for better using 16:9 screen ratios
      and making Liferea usable on touchscreen
    * Optional AMP / HTML5 rich content fetching feature
    * Upgrade to WebKit2: This is an important security improvement!
    * Added a "Do Not Track" preference (disabled per-default)
    * Reordered columns in 'Normal' email-like view to have the date column always at the end
    * Plugins switched to Python3 libpeas loader
    * Full screen support for videos
    * Simplified external browser support

* Experimental support for InoReader and Reedah online services * Added category/folder support for TheOldReader * Added folder auto-removal for TinyTinyRSS & TheOldReader

* Removed libindicate support * Removed libnotify code (re-added as a plugin) * Removed tray icon code (re-added as a plugin)

Important fixes

    * Fixes unhiding from tray icon when activated via GApplication (hidden window problem)
    * Fixes #538: toggle_visibility() does not make a minimized window visible again (trayicon problem)
    * Liferea now uses ETags and If-None-Matches on feed updates
Please help fixing any leftover bugs and UX issues!

Show Your Support

Nowadays it is hard to know how many users are left out there. If you like the release of 1.12 show it by giving the project a star at Github!!!


Get a tarball or checkout the code from Github!

Liferea 1.12-rc3 Released

This is another 1.12 release candidate fixing bugs and updating a lot of translations.

    * Fixes #459: Fixes GtkDoc warnings
    * Fixes #415: Filter commands are not asynchronous
      (Rich Coe)
    * Fixes #363: Missing space above internal browser address bar
      (reported by nekohayo, patch by Mikel Olasagasti)
    * Fixes #208: All "Unread" search folder items marked read at once
    * Fixes #251: Liferea does not always use theme icons when it is launched
      on system startup (reported by GreenLunar, fix by Leiaz)

* Updated Finnish translation (Jorma Karvonen) * Updated Latvian translation (Rihards Prieditis) * Updated Albanian translation (Bensik Bleta) * Updated Hungarian translation (Balázs Úr) * Updated Brazlian translation (Rafael Ferreira) * Updated French translation (Guillaume Bernard)


Get a tarball or checkout the code from Github!

Writing Liferea Plugins Tutorial Part 2

Let's continue the plugin tutorial. The last installement was on how plugins work and how to create the boilerplate for a new plugin. Now let's look into how to access Liferea UI elements and how to modify them.

Accessing UI elements

Using the plugin boilerplate for a Liferea.ShellActivatable (a plugin that activates once the Liferea shell, which as an object comprises the entire main window UI, has been setup) we get a member variable named "shell"
    shell = (type=Liferea.Shell)
which can be used to look up GTK objects by name using
    shell.lookup(<some name>)
Some interesting names to look up are:
Name Description
mainwindowThe main GtkWindow
leftpaneThe vertical pane containing the feed list
rightpaneThe vertical pane containing the rest
feedlistThe feed list GtkTreeView
itemlistThe item list GtkTreeView
browsertabsThe tabs notebook of the item view
statusbarThe main window status bar
This list not being exhaustive you can grep the code for more uses
rgrep liferea_shell_lookup src/
in general when you want to modify existing UI elements or add extra elements to the UI above list should be a good start.

Example: Modifying the feed list

Here is a simple example to hide the 2nd column of the feed list GtkTreeView. To do this we use the "shell" member to look up the "feedlist" GtkTreeView and ask it for the 2nd column which we then hide:
from gi.repository import GObject, Peas, PeasGtk, Gtk, Liferea, Gdk

class NrColumnHidePlugin (GObject.Object, Liferea.ShellActivatable): __gtype_name__ = 'NrColumnHidePlugin'

object = (type=GObject.Object) shell = (type=Liferea.Shell)

def do_activate (self): treeview = ("feedlist") column = Gtk.TreeView.get_column (treeview, 1) Gtk.TreeViewColumn.set_visible (column, 0);

def do_deactivate (self): return
This is all done on activate, nothing needs to be done on deactivation.


Also check out the other plugin tutorial posts

Writing Liferea Plugins Tutorial Part 1

Some time ago a fellow Liferea user asked about documentation on writing Liferea plugins. I see the need and the benefit and want to start doing so with a series of blog posts that later can be compiled into a tutorial to be included on the website/sources.

Plugins with GObject Introspection

First it is important to know that Liferea 1.10+ uses GObject Introspection (GI) and libpeas to allow implementing plugins. This quote from the GNOME wiki explain how GI works:

GObject introspection is a middleware layer between C libraries (using GObject) and language bindings. The C library can be scanned at compile time and generate a metadata file, in addition to the actual native C library. Then at runtime, language bindings can read this metadata and automatically provide bindings to call into the C library.

The important point is: by Liferea using GI (as all GNOME applications and many other GTK applications do now) plugins can be written in practically any scripting language. Most users seem to favour Python and all current plugins included with the Liferea sources are in Python. Note that this tutorial will also focus on Python only.

How are plugins triggered from within Liferea?

Ok, I can write a script in Python! How will Liferea run it and when?

This is where libpeas comes in, which is a basic library to implement a plugin system. If you click the preferences dialog and switch to the "Plugins" button you see a dialog provided by the PeasGtkPluginsManager class of libpeas. Detection, activation and configuration of plugins is handled by libpeas.

Now for the "When?" question: To properly allow applications to hook plugins into different parts of the applications libpeas allow an application to define one or more so called "Activatable" interfaces.

For simplicity for Liferea I decided to only support a LifereaShellActivatable interface. This means all plugins are activated together with the LifereaShell instance (src/ui/liferea_shell.c). This class represents the main application window holding all widgets. So when your plugin gets activated all widgets exist and you can access everything like extending or modifying the GUI, changing settings, everything you can think of.

Note: in the code there are two more interfaces: that are used to implement two important features (GNOME keyring support and a simple media player). Feel free to use those two, but be aware that they work differently and activate at other times and not just once as the LifereaShellActivatable.

Using LifereaShellActivatable

If you script in Python using LifereaShellActivatable means simply deriving a new class from it. For example:
from gi.repository import GObject, Peas, PeasGtk, Gtk, Liferea, Gdk

class ExamplePlugin (GObject.Object, Liferea.ShellActivatable): __gtype_name__ = 'ExamplePlugin'

object = (type=GObject.Object) shell = (type=Liferea.Shell)

def do_activate (self): # Do something here...

def do_deactivate (self): # Maybe do somethin here too...
The activate() and deactivate() methods are required by libpeas and provide you with the starting points to do stuff. By fetching the "Liferea.Shell" instance you gain access to the main window. Using this you can both lookup widgets or other Liferea classes like the Liferea.FeedList to perform actions against business objects of Liferea.

Providing a plugin configuration

Along with the actual plugin code libpeas requires a plugin configuration file defining the language the plugin is implemented with and metadata (name, description, website...) for this plugin. Such a file looks like this:
Name=Example Plugin
Description=Illustrates how to implement plugins in Liferea
Authors=Lars Windolf 
Copyright=Copyright © 2014 Lars Windolf
Most important is the "Loader" setting indicating the correct scripting language and the "Module" setting which together with the "Loader" setting as "python" indicates that or plugin script is to be named "". Both the "" plugin script and it's "example.plugin" config file need to be put into the Liferea plugins directory...

Where to put my plugin script?

There are two possible locations for the plugin script (and it's configuration file): Note that paths can be different with different XDG settings.

When writing and testing don't bother installing the plugin in the package directories. Just put it in ~/.config/liferea/plugins, fire up Liferea.

More about how to check for activation, debug problems and handling enabling/disabling in the next installment of this tutorial!


Also check out the other plugin tutorial posts

Liferea 1.12-rc1 Released

This is a first release candidate for new stable line 1.12

Major changes since 1.10

Changes since 1.11.7

    * Github #348: Added support for downloading content that
      cannot be displayed by HTML widget (e.g. PDFs)
    * Github #355: Migrate to Python3 libpeas loader
      (patch by picsel2)
    * Github #311: Upgrade to WebKit2
      (patch by Leiaz)
    * Github #292: Show new item count in tray icon
      (patch by mozbugbox)
    * Github #297: Minimize to systray on window close
      (patch by Hugo Arregui)
    * Github #325: Auto-fitting, translated license
      (patches by GreenLunar and Adolfo Jayme-Barrientos)

* Fixes Github #73: Problem with favicon update (reported by asl97) * Fixes Github #177, #350: Tray icon not scaled properly (patch by mozbugbox) * Removes GeoIP rendering via OSM to avoid exposing users to remote JS library resources. (reported by Paul Gevers) * Fixes Github #337: Case sensitive sorting (reported by Pi03k) * Fixes Github #361: Show all enclosuers (Leiaz) * Fixes Github #368: Segfault on liferea-feed-add (Leiaz) * Fixes Github #382: Broken Auto-Detect/No Proxy setting (Leiaz) * Fixes Github #383: Per feed don't use proxy setting is broken (reported by Leiaz)

* Github #309: Update of Japanese translation (IWAI, Masaharu) * Github #329: Update of Hebrew translation (GreenLunar) * Github #330: Update of Spanish translation (Adolfo Jayme-Barrientos) * Update of Swedish translation (Andreas Ronnquist)


Get a tarball or checkout the code from Github!

Liferea 1.12 now with Webkit2

Some minutes ago I'v added Leiaz extensive change for switching to Webkit2. This is great news because for quite some time Webkit1 has not seen any security updates anymore and many applications still on Webkit1 expose there users to quite some risk.

What's different in Webkit2?

The most important change is Webkit being multi-process. For applications using Webkit this means they have to talk to the background process to scroll, copy text, get context menues and other stuff. The Webkit2 way to do the talking is to write a Webkit extension that is loaded when the background process starts which allows us to send DBUS commands.

As for performance it seems faster. But you might want to try yourself!

Distro Support

To compile with Webkit2 you need at least the following Linux distribution versions

No Travis CI anymore

Due to the Ubuntu 16.04 not yet supported by Travis I had to disable the test builds as the fail installing the Webkit2 package :-(

Liferea Trick #9: Skimming Through the Headlines

I'm not sure about how many users are aware of the feature, but I'm certain it is worth to know about as it saves a lot of clicking and pointing with the mouse. If you are a keyboard user it's worth knowing about the hotkey to skim through headlines.

Remember the Hot Key

As this hotkey is configurable check the preference dialog ff you are not sure about the setting. The default setting is <Ctrl>-Space...

How it Works...

By using this hot key you can navigate the article pane and the item list view at the same time. As long as the article pane allow vertical scrolling it scrolls down. Once you reach bottom Liferea jumps to the next unread article.

Using the headline skimming hotkey is like a "Next Unread And Scroll Down" menu option...

Recent Liferea Tricks

Liferea Trick #8: Change Menu Accelerators

When you are not satisfied with the menu key bindings defined by Liferea do not despair it is easy to change them!

Variant #1: Edit ~/.config/liferea/accels

This variant is 100% portable and should work for everyone. Open ~/.config/liferea/accels in your favourite editor. This file is loaded upon startup by Liferea and contains lines like these:
; (gtk_accel_path "<Actions>/AddActions/NewVFolder" "")
; (gtk_accel_path "<Actions>/GeneralActions/SearchMenu" "")
; (gtk_accel_path "<Actions>/ItemActions/ToggleItemFlag" "<Primary>t")
; (gtk_accel_path "<Actions>/GeneralActions/PrevReadItem" "<Primary><Shift>n")
Note how only the "ToggleItemFlag" and the "PrevReadItem" line have defined key bindings, while "NewVFolder" and "SearchMenu" don't.

To change a key binding first remove the semicolon at the start of the line and then adapt or clear the key binding field. Choose prefixes like "<Primary>" (for Ctrl), "<Alt>", "$lt;Shift> as needed and append the key after it.

Variant #2: Enable Editable Accelerators with your Linux Distro Settings

This variant is hard to document as different distributions have different setting dialogs. Some expose a setting to enable life editing of key bindings. Once this is enabled you can open a menu hover over a menu option and press the accelerator you want to assign. It should show up instantly.

Recent Liferea Tricks

Liferea Trick #7: Force Read Full Posts

The Problem

When you have subscribed to an interesting feed that does not provide full posts it can be frustrating. Short of using website scraping as described in the latest post there is nothing you can do to enhance the feed content.

There are legitimate reasons for feed publishers to do so. One might be that the site is earning by display ads, another might be that the publisher wants to engage users directly on their own website.

How To Solve It?

So why not follow that wish and simply read the entire website? Liferea allows you to do so by enabling an option in the subscription properties. Just open the subscription properties dialog by right clicking the subscription as selecting "Properties ..." and select the last tab "Advanced":

Here you can enable the second option "Auto-load item link ...". From now own you will read the website directly and see full content!

Recent Liferea Tricks

Liferea Trick #6: Website Scraping

Not every interesting website provides a feed. Some feeds are broken. And some websites do provide summaries only or no content at all. Besides asking the owner of the website to add a feed or provide more details the only choice left might be to "scrape" the website content.

Read about how to scrape websites with Liferea

Recent Liferea Tricks

Liferea Trick #5: Privacy with a SOCKS Proxy

Starting with Liferea 1.10 you can use a SOCKS proxy. This is possible because Liferea uses the libproxy support provided by the libsoup networking library since 1.10.

What is a SOCKS Proxy?

SOCKS stands for "socket secure" it simply means to use an encrypted connection for whatever you do. Configuring a SOCKS proxy in your desktop environment means that you want all applications to do internet access via an encrypted connection to a safe server you have access to.

Why Use a SOCKS Proxy for Feed Reading?

Well, this of course is useful if you are in an environment were you do not want others to see what you are reading. Be it political blogs or private but unencrypted feeds. Also you simply might not want for your employer to know what servers you are polling news feeds from anyway. There are many good and bad reasons.

How To Use SOCKS Proxy with Liferea and GNOME?

First please note that Liferea supports using a SOCKS proxy only via the GNOME network preferences. Actually it relies on libsoup using the SOCKS settings from there.


  1. Liferea 1.10+ with GNOME desktop
  2. You have a private server to use as a proxy
  3. You can connect via SSH to this server

Step 1: Connecting the SOCKS Proxy

There are many ways to do this and many online tutorials. The easiest way is to use SSH like this
ssh -D 8080 <user>@<private server>

Step 2: Client Proxy Configuration

So the first thing to do is to configure Liferea to use the GNOME network settings:

Ensure to set the preferences to proxy auto-detect as shown in the screenshot above. Next go to the GNOME preferences and configure a SOCKS proxy on "localhost" and port "8080" or whatever port you used when you ran the SSH command.

That's it! Try to update feeds in Liferea and watch out for errors in the status line.

What About Older Liferea Versions?

If you are running an older version of Liferea have a look at this post about a SOCKS proxy workaround using the tool redsocks.

Recent Liferea Tricks

Liferea Trick #4: Full Screen Mode

Are you using a netbook and have not much screen real estate? Then wether it is a mail client or web browser or news aggregator using it in full screen mode gets you more content visible. Less space is wasted for menu elements and window decoration.

In Liferea press F11 or select "View" -> "Fullscreen" to enable full screen mode.

If you want to save even more vertical space consider hiding the toolbar by enabling the option in the preferences dialog.

Recent Liferea Tricks

Liferea Trick #3: Use Feed Auto Discovery

This is an easy one: Don't bother entering the exact feed URL when subscribing!

These days it is standard for websites to support feed auto discovery. Many blogs and websites actually do not add feed subscription icons and links anymore. The feed link is just included in the HTML markup and every aggregator can extract it. No need for you to look for it.

To make it even simpler combine with trick #2 and use drag&drop! On every websites whose feed you want to add just drag the favicon from the browser location bar into Liferea. Most browsers do interpret this as dragging the location. Do not even bother copying the URL.

Be lazy :-)

Recent Liferea Tricks

Liferea Trick #2: Drag and Drop URLs

Maybe it is obvious, but you can of course use Drag&Drop to add feed subscriptions to Liferea.

You can drag

and Liferea will create a new subscription.

You can also Drag&Drop any web sites URL and Liferea will try to auto-discover the feed URL from it.

Note that dragging URLs into the item browser pane or a browser tab will just launch the URL in the internal browser.

Recent Liferea Tricks

Liferea Trick #1: Middle Mouse Button Clicking

For all the readers of this development blog I want to share same hidden usability things in Liferea. Today I want to start with using the 3rd mouse button.

Place Where To Use Middle Click

  1. Subscription List: Click on any subscription or folder to mark everything in the subscription or folder as read.
  2. Item List (on flag column): Click on the flag column to toggle the flag for an item without selecting it.
  3. Item Lists (except flag column): Click everwhere beside the flag column and you toggle the read status of the item even without selecting it.
  4. Browser View: In any browser view, be it a browser tab or the item view pane middle click any link to open it in a new browser tab within Liferea.

Recent Liferea Tricks