Fwd: Help for an extension: Call a function when switch workspace in overview

[Amy <mathematical coffee gmail com>]

Forgot to reply on-list; storing this in the archives for posterity
(some future person might want to know about looking up gir
files/converting typelib files/generating docs from them).


---------- Forwarded message ----------
From: Amy <mathematical coffee gmail com>
Date: 4 September 2012 15:32
Subject: Re: Help for an extension: Call a function when switch
workspace in overview
To: Bazon Bloch <bazonbloch arcor de>


On 4 September 2012 15:00, Bazon Bloch <bazonbloch arcor de> wrote:
> Is there a way how to find out which connect events are available? I
> searched /usr/share/gnome-shell/* for a file including "workspace-switched",
> but found nothing.

Ahh, I remember going through the same pain as you when I first
started developing extensions!

Here is stuff I've learned along the way:

A good place to look is documentation online, if you can find any.
Most of it lives on developer.gnome.org. For example:

* http://developer.gnome.org/st/stable/ for imports.gi.St
* http://developer.gnome.org/shell/unstable/ for imports.gi.Shell (<--
I found that one hard to find, since it's in unstable instead of
stable!)

These pages will give lists of signals available for each class.

If you can't find the documents (Meta doesn't have them), you can look
in the *.gir files, which define how the C functions map to the JS
functions for each library (imports.gi.Meta, imports.gi.Gtk, ...). You
can find the signals quickly by grepping for 'signal':

grep 'glib:signal' Meta-3.0.gir
# will give me a list of signals in the Meta library.
# ... (lots of signals)
      <glib:signal name="workspace-changed" when="last">
      </glib:signal>
# ... (lots more signals)

When you find the signal you're interested in you can go into the .gir
file and see what it is owned by (in this case Meta.Screen), so you
know that if you want to listen to the 'workspace-changed' signal you
will have to connect to a Meta.Screen (global.screen in this case).

In terms of finding the gir files, I found some in /usr/share/gir-1.0.

I think some of them only appear there if you install either the
relevant -dev package, or perhaps a gir package.

Some of them I couldn't find at all (e.g. Meta, Shell, St) because
they are considered "private", but you can find these here:

* /usr/lib/gnome-shell (Shell, St)
* /usr/lib/mutter (Meta)

However these are .typelib files, which is like a compiled version of the gir.

To conver the .typelibs into readable .gir files you can use

g-ir-generate /usr/lib/mutter/Meta-3.0.typelib > Meta-3.0.gir

(the g-ir-* tools are provided by package gobject-introspection on
ubuntu; I think you can install them from a repository on the web
somewhere too).

Sometimes g-ir-generate will complain about not being able to find
various other typelibs, for example if you try to generate Shell.gir
from the typelib:

g-ir-generate /usr/lib/gnome-shell/Shell-0.1.typelib
** (g-ir-generate:9599): ERROR **: failed to load typelib: Typelib
file for namespace 'St', version '1.0' not found
Trace/breakpoint trap (core dumped)

In this case it's trying to find St-1.0.typelib, which is in
/usr/lib/gnome-shell, so you can include it using --includedir like so
(it also needs to find Meta-3.0.typelib in /usr/lib/mutter, I think by
default just /usr/lib/girepository-1.0 is included):

g-ir-generate --includedir=/usr/lib/gnome-shell
--includedir=/usr/lib/mutter /usr/lib/gnome-shell/Shell-0.1.typelib

and then it will work.

(Note - there are many .typelib files in
/usr/lib(64?)/girepository-1.0, more than there are .gir files in
/usr/share/gir-1.0).

Then if you like you can even generate HTML documentation from the
.gir files (but if you can find documentation online use that instead,
it looks better):

mkdir mutter-docs
g-ir-doc-tool Meta-3.0.gir -o mutter-docs

Then turn the output (yelp files) into HTML:

yelp-build html mutter-docs

And then load index.html in a browser and you have some basic
browsable documentation, complete with a list of signals (so if you
click on the Meta.Screen page it has a list of signals you can connect
to, although it is a bit sparse on explanation).

PS - re closing a window through the hover X button in the overview,
you'll probably have to monkey patch that. See
/usr/share/gnome-shell/js/ui/workspace.js - the code to do with
this.closeButton, and in particular, WindowOverlay._closeWindow
appears to handle the closing of a window when the button is clicked.

PPS if you really did want to look up a list of signals, you can do it
with GObject, but I think it is much much more helpful to browse the
documentation/girs:

const GObject = imports.gi.GObject;
GObject.signal_list_ids(GObject.type_from_name('MetaScreen')).map(function
(id) { return GObject.signal_name(id); });

where signal_list_ids lists all the ids belonging to class MetaScreen,
and signal_name(id) gets the name for that signal (documentation:
http://developer.gnome.org/gobject/stable/gobject-Signals.html).

Hope that helps! (And the mailing list is a great way to ask questions
when you get fed up of wading through documentation, I still do heaps
of that :))

> Entering global.screen.connect in looking glass didn't help either, and
> unfortunately, I wasn't successful in finding the source code for
> global.screen (that's what I tried as a beginner.)
>
> (Specific I would be interested in the events:
>  * show overview
>  * close a window through the hover x-Button in the overview)
>
>
> _______________________________________________
> gnome-shell-list mailing list
> gnome-shell-list gnome org
> https://mail.gnome.org/mailman/listinfo/gnome-shell-list
>