This post is going to be based partially on the source of Coverflow Alt Tab, plus some of the source files that are already included in GNOME 3.
Also, a few notes here: it appears at this time that there is no way to easily import your schema into the GSettings backend. This may be added at a future time. So, any settings that you make will essentially be unstructured and possibly break if somebody messes around with them.
The first thing for us to do is to create a new XML schema for us. This schema holds the keys to our values, as well as default values and descriptions. There’s some documentation on the GNOME website, so i will only go over a small portion of what is there, given that I only understand a small portion. 🙂
For our purposes, we will define two keys: one string key which will be the text to display, and a boolean value that we will mess around with later. For now, let’s define the XML schema:
<?xml version="1.0" encoding="UTF-8"?>
<schemalist>
<schema id="com.rm5248.testplugin" path="/org/gnome/shell/extensions/rm5248/">
<key type="s" name="hello-text" >
<default>"Hello, World!"</default>
<summary>The text to display</summary>
<description>The text to display</description>
</key>
<key type="b" name="wait" >
<default>false</default>
<summary>Wait?</summary>
<description>Do you wait until OK?</description>
</key>
</schema>
</schemalist>
This is pretty straightforward: you have a schema with a name(com.rm5248.testplugin) and two keys, a string value called ‘hello-text’ and a boolean vaue called ‘wait’. Once we have written the XML file, we need to generate the binary version of it. To do that, simply use the glib-compile-schemas tool:
glib-compile-schemas schemas/
Now that we have our compiled schema, it’s time to retrieve settings from the GSettings database. In order to do that, we will need this lib.js file from CoverflowAltTab. From the copyright, it appears to be from the GNOME sources, however I have been unable to find where it originally comes from.
Now that we have our schema compiled and in the schemas/ directory, it’s a very simple process to get the default settings(as we haven’t changed them at all.). In fact, here’s the entire code:
const Gio = imports.gi.Gio;
const ThisExtension = imports.misc.extensionUtils.getCurrentExtension();
const Lib = ThisExtension.imports.lib;
const RM_SCHEMA = 'com.rm5248.testplugin';
const TEXT_KEY = 'hello-text';
const BOOL_KEY = 'wait';
let settings = null;
function init() {
// Create the new settings
settings = Lib.getSettings( RM_SCHEMA );
}
function enable() {
log( settings.get_string( TEXT_KEY ) );
log( settings.get_boolean( BOOL_KEY ) );
}
function disable() {
}
For now, we’re just printing out the settings to the console, which is not very useful. We’ll expand this in a bit, but before we do that let’s make a GTK widget to set the settings. Looking at the GNOME documentation, we see that we can change settings by having a prefs.js file with a method buildPrefsWidget.
A quick note before we get started here: when constructing a C object, the parameters to the object(in the {} syntax) are properties to set on the object. Take for example the properties on GTKLabel: if you want to set the ‘angle’ property when constructing, you would do:
new Gtk.Label( { angle: 20 } );
Do this for all the properties that you wish to set when you create the object.
Now, moving on to the actual code of the prefs.js file. Everything here is fairly straightforward if you’ve done GTK+ programming before. Here’s the code that will pop up a GTK+ widget:
function buildPrefsWidget(){
let frame = new Gtk.Box( { orientation: Gtk.Orientation.VERTICAL, border_width: 10, spacing: 10 } );
//There are two settings, so we will have one that changes the text and one that changes
//the boolean value.
//Create an EntryBuffer to store the text in
let entryBuffer = new Gtk.EntryBuffer( { text: settings.get_string( TEXT_KEY ) } );
let textBox = new Gtk.Box( { orientation: Gtk.Orientation.HORIZONTAL, spacing: 10 } );
let textLabel = new Gtk.Label( { label: "Hello text", xalign: 0 } );
let textEntry = new Gtk.Entry( { buffer: entryBuffer } );
//Gtk.Entry implements GtkEditable interface, which is where the 'changed' signal comes from
textEntry.connect( 'changed', function( widget ){
settings.set_string( TEXT_KEY, widget.get_text() );
} );
textBox.pack_start( textLabel, true, true, 0 );
textBox.add( textEntry );
//Let's change our boolean value now
let boolBox = new Gtk.Box( { orientation: Gtk.Orientation.HORIZONTAL, spacing: 10 } );
let boolLabel = new Gtk.Label( { label: "Do we wait?", xalign: 0 } );
let boolRadio = new Gtk.Switch( { active: settings.get_boolean( BOOL_KEY ) } );
//Gtk.Switch has an 'activate' signal, but don't connect to that directly.
//Instead, the docs say to use the 'notify::active' signal
boolRadio.connect( 'notify::active', function( widget ){
settings.set_boolean( BOOL_KEY, widget.get_active() );
} );
boolBox.pack_start( boolLabel, true, true, 0 );
boolBox.add( boolRadio );
frame.add( textBox );
frame.add( boolBox );
frame.show_all();
return frame;
}
To test this out, re-load the shell (ALT+F2, r, enter), and open up gnome-tweak-tool. Under ‘Extensions’, there should now be a small cog for the ‘settings example’ extension. If you open that up, you should see the two settings that we made: one for the text, and one for the boolean value. By changing these values, you can change what the extension will print out when the plugin is loaded.
You can also use dconf to see the values directly, once you have saved them first. Change a value with gnome-tweak-tool, open up dconf and navigate to /org/gnome/shell/extensions/rm5248/, and you will see the settings that you have made. Remember though, they only appear there if they are different from the defaults; this may not be true for all programs, but it is true for gnome-shell extensions.
You may find the complete source here.