Take the 2-minute tour ×
Ask Ubuntu is a question and answer site for Ubuntu users and developers. It's 100% free, no registration required.

I have been wanting to develop some Gnome Shell extensions since they are just in javascript, however I have been looking and there is practically zero documentation, everywhere I look people just say to use the basic Gnome documentation, but this does NOT help, I can not find any documentation for the imports for extensions, or any kind of javascript api for the extension development, I tried looking through some of the tutorials (most of which are for Gnome 3.0, not 3.2), but nothing is helping.

Does anyone know if they are in progress of writing documentation for extension development? I would really love some good documentation...

share|improve this question
add comment

4 Answers

up vote 3 down vote accepted

The reason I'm not happy with the demo code and tutorials is that they introduce a bunch of random imports and never explain what they are or how to use them. I'm constructing my own answer that others can add to, so that people can actually know what functions they can call, what they can import, etc.

There is generated documentation for Gnome Shell, but it is somewhat incomplete — I couldn't find most of the things I saw in various tutorials, examples and published extensions.

The only really reliable documentation is the Gnome Shell source itself. There simply isn't any other up-to-date or complete way to know what's available.

These two starting points are particularly good:

The C source shows that there is an important object called global that doesn't need to be imported, and provides access to things like the window manager (including keybindings), the session information, the screens available and other such things. Here's the source:

I wanted to know how to use the global.display object, and for now the best documentation is that provided by Alan Knowles.

Other things can be imported via the GObject introspection bindings, for example:

In general, you can look through the reference documentation for the various Gnome components to find other imports.

A note on the looking glass: There are some quirks about using these imports in the looking glass though — I wasted a lot of time just trying to test things out on the fly. For example:

const Clutter = imports.gi.Clutter;

...won't work, because Clutter already exists. But then:

const MyClutter = imports.gi.Clutter;

...also won't work; MyClutter is undefined and can't be used. You have to do:

MyClutter = imports.gi.Clutter;

Of course, in this case Clutter already exists, so it's not really necessary. But since it's not documented what is and isn't already in the looking glass namespace, if you try to import something and have these problems, keep it in mind.

Remaining questions:

  • What is Mainloop? This is imported in main.js and appears to have functions related to the GLib main loop. Is there documentation for this?
  • What is imports.misc? It seems to have some really useful things in there, like ExtensionUtils — what's that?
  • How do you use DBus? What about introspection?
share|improve this answer
add comment

Documentation is lagging a bit, one potential source of information is Musings of an OS plumber, e.g. this post on updating GNOME Shell extensions to work with version 3.2

Depending on what information you want, you might try the gnome mailing list.

share|improve this answer
    
Whilst this may theoretically answer the question, it would be preferable to include the essential parts of the answer here, and provide the link for reference. –  hhlp Feb 6 '13 at 17:03
add comment

Did you see this page already: https://live.gnome.org/GnomeShell/Extensions ?

share|improve this answer
    
Whilst this may theoretically answer the question, it would be preferable to include the essential parts of the answer here, and provide the link for reference. –  hhlp Feb 6 '13 at 17:02
    
@hhlp The OP wants documentation, way too much to actually put in an answer, so I think this is fine. –  Seth Feb 8 '13 at 4:21
add comment

This Step by step tutorial to create extensions for gnome 3.4 may help: https://live.gnome.org/GnomeShell/Extensions/StepByStepTutorial

share|improve this answer
    
It says: "[The API] is very difficult, because of the lack of documentation...". Oh well. –  detly Feb 8 '13 at 5:37
    
I'm awarding you the bounty because that landing page has many useful links :) –  detly Feb 9 '13 at 2:38
    
Thank you detly! –  agusti Feb 15 '13 at 0:49
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.