notes & snippets

Notes on writing gnome-shell extensions

Musings of an OS plumber is an excelent source of information on the basics of gnome-shell extensions development (probably the best, so far), but it is already a bit outdated because of some changes in the 3.2 gnome-shell API. These notes are an attempt to complement the information already available.

1. extension.js must have at least three functions: a) init(), which runs when the extension is loaded (when the shell starts). b) enable(), which runs when the extension is enabled (via gnome-tweak-tool, for example) c) disable(), which runs when the extesion is disabled.

   Most existing extensions will have to adapt to this change, and move most of their code to enable. These changes mean that you must define a way of returning to the original state in the shell.

2. extensions are loaded after the main elements of the shell are created. This won’t affect many extensions, but it means that there are limits to what one can do with monkeypatches. One can, of course, try to destroy the original elements of the shell before and then recreating them with some monkeypatched versions, but that isn’t very easy.

   This means that some extensions will have to be a bit more complex than they used/needed to be. For example, fpmurphy’s noa11y extension can’t simply modify imports.ui.panel.STANDARD_STATUS_AREA_SHELL_IMPLEMENTATION, because that is defined before the extensions are loaded. My take on it is:

   const Panel = imports.ui.panel;
   const Main = imports.ui.main;
   
   idx = null;
   
   function enable() {
       idx = Panel.STANDARD_STATUS_AREA_ORDER.indexOf("a11y");
       Main.panel._rightBox.get_children()[idx].destroy();
       // addToStatusArea would throw an error on disable if we don't set this to null 
       Main.panel._statusArea['a11y'] = null;
   }
   
   function disable() {
       let indicator = new Panel.STANDARD_STATUS_AREA_SHELL_IMPLEMENTATION["a11y"];
       Main.panel.addToStatusArea("a11y", indicator, idx);
   }
   
   function init() {
   }
   

3. I wish looking glass had some kind of reflection (that would be one hell of a great idea for an extension…). For now, knowing one’s way between the shell javascript files is required. Thankfully, they are quite well organized. I wish there was some more documentation on the gi imports, though (like gi.Shell).

4. One can evaluate javascript in the shell using its DBus interface (org.gnome.Shell:/org/gnome/Shell/:org.gnome.Shell->Eval(s)), which in theory would allow for the development of external extensions. However, the shell objects are not well supported this way. As long as the code one calls doesn’t return objects, it should be fine, though.