Gnome shell: my first extension
Lately I’ve been playing with gnome-shell, I wanted to create an extension and finally came up with a result. The experience was actually a bit painful due to a lack of documentation. In this post I will present the simple extension I’ve got and provide explanations whenever I can. However, this should be taken with carefulness since I’ve started with few days ago. Nevertheless the extension is pretty simple and I think it can help someone, starting by me.
How it looks like:
It simply displays in the top panel an indicator retrieved from a web site. For information, the web site I used is Transfer Wise but I encourage you to change for data that interests you.
- I am currently using version 3.16.4 of Gnome Shell.
- This post is not a tutorial to start with gnome-shell, it would have been a really tough work. There is actually not so much documentation online. I will just recommend you this link: http://mathematicalcoffee.blogspot.fr.
1. Before starting
There are few apps and commands you should know before starting.
- Tweaks tool
It allows to see gnome-shell extensions installed and enable/disable/remove them. It actually does much more but here we won’t need the other features.
You can find the details on this page https://wiki.gnome.org/Apps/Logs. This app is used to watch many different kind of logs. We will use it to display the logs of our extension.
- Commands and shortcuts
- Open the “gnome-shell popup” (not sure how it’s called): ALT + F2
- Close the “gnome-shell popup”: ESC or Enter
- Restart gnome-shell: open the popup + write “r” + press enter. (the screen should blink)
- Open looking glass: open the popup + write “lg” + press enter. (Looking glass is a kind of console + debugger + inspector for Gnome Shell)
- Quit looking glass: ESC
- Gnome-shell crashed:
2. Create a new project
Creating a new extension is easily done by writing this command in a terminal:
It will prompt for a name, a description and a uui. You will be able to modify these metadata later if you like to. For my extension I entered:
- name: Transfer Wise Indicator
- description: Get CHF transfer rate
- uui: firstname.lastname@example.org
Once the information submitted an editor will pop up showing the default code for an extension:
There is a complete description of this code in the official documentation here.
If you prefer you can re-open the code in you favorite editor. The extensions are located in this folder:
You should see a folder named after the uuid you gave (If there are other folders it means you already installed gnome extensions). Inside there are three files:
- metadata.js (metadata: name, description, uuid, gnome-version, …)
- stylesheet.css (CSS to specify some style on your UI components)
To install the extension you need to open the Tweaks Tool. You should see it in the list, switch it on. The extension is a button with an icon in the top panel. When you click on it a popup appears with “Hello World”.
3. Start writing our own extension
Now we have a new project we can start modifying it. For instance if you change the label.
Then restart gnome-shell to make the change effective.
ALFT+ F2, write "r" and press enter. Normally if you click
again on the button you should see the change.
a. Clean up
We will actually reuse the hello world extension because it has similarities with what we want to achieve. Indeed, it touches the same area of gnome-shell which is the top menu. Of course, instead of an icon we would like a text taken from a web service. Also, we don’t really want any popup. So let’s do some clean up.
I removed the functions showHello and hideHello and change the button to display a text instead of the icon. Try it by refreshing gnome-shell. It looks already promising!
b. Let’s go further
It is not that simple to continue without knowledge and clear documentation. So what I done is I went on the Gnome extension web site https://extensions.gnome.org and searched for an extension close to mine and took a look at the code. Remember extensions are installed in this folder: “.local/share/gnome-shell/extensions/”. I used this one Forex indicator which is actually much more complex compare to what I wanted to build. Since it is open source I took the opportunity to get inspiration.
By the way, I would like to thank Trifonovkv the creator of this application.
Before writing too much code I would like to introduce you how to log things. An easy way is to use
You can see the logs by opening the “Logs” application.
3. Step by step
a. Extends PanelMenu.Button
We will change a bit direction to use a
PanelMenu.Button instead of a
St.Bin. But the most important is, we will extends this class in order
to add custom features. Let’s start slowly:
This does exactly the same as before in terms of result but behind the scene we created our own class TransferWiseIndicator.
b. HTTP request
Now it’s time to get real data in order to display something else. Let’s see how to do an HTTP call:
The library used is Soup. We are missing the value for URL and TW_AUTH_KEY but I think you got the idea.
Now we know how to display a text in the top menu and to get data with an HTTP request. In theory if we merge that we are almost done. However, it’s not that awesome if the text doesn’t refresh. To do so, we will use another import:
Create a loop:
The refresh function will be part of our class and call every 10 sec.
d. Put things together
Here the full project on Github.