SignalManager.SignalManager

SignalManager.SignalManager — A convenience object for managing signals

Functions

Properties

Object _object  
Array _storage  

Object Hierarchy

    Object
    ╰── SignalManager.SignalManager
  

Description

The SignalManager is a convenience object for managing signals. If you use this to connect signals, you can later disconnect them by signal name or just disconnect everything! No need to keep track of those annoying signalIds by yourself anymore!

A common use case is to use the SignalManager to connect to signals and then use the disconnectAllSignals function when the object is destroyed, to avoid keeping track of all the signals manually.

However, this is not always needed. If you are connecting to a signal of your actor, the signals are automatically disconnected when you destroy the actor. Using the SignalManager to disconnect all signals is only needed when connecting to objects that persists after the object disappears.

Every Javascript object should have its own SignalManager, and use it to connect signals of all objects it takes care of. For example, the panel will have one SignalManger object, which manages all signals from GSettings, global.screen etc.

An example usage is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
MyApplet.prototype = {
    __proto__: Applet.Applet.prototype,

    _init: function(orientation, panelHeight, instanceId) {
        Applet.Applet.prototype._init.call(this, orientation, panelHeight, instanceId);

        this._signalManager = new SignalManager.SignalManager(this);
        this._signalManager.connect(global.settings, "changed::foo", this._onChanged);
    },

    _onChanged: function() {
        // Do something
    },

    on_applet_removed_from_panel: function() {
        this._signalManager.disconnectAllSignals();
    }
}

Functions

_init ()


_init (Object   object);

Parameters

object

the object owning the SignalManager (usually this)

 

connect ()


connect (Object     obj,
         string     sigName,
         function   callback,
         Object     bind,
         boolean    force);

This listens to the signal sigName from obj and calls callback when the signal is emitted. callback is automatically binded to this._object, unless the bind argument is set to something else, in which case the function will be binded to bind.

This checks whether the signal is already connected and will not connect again if it is already connected. This behaviour can be overridden by settings force to be true.

For example, what you would normally write as

1
global.settings.connect("changed::foo", Lang.bind(this, this._bar))

would become

1
this._signalManager.connect(global.settings, "changed::foo", this._bar)

Note that in this function, the first argument is the object, while the second is the signal name. In all other methods, you first pass the signal name, then the object (since the object is rarely passed in other functions).

Parameters

obj

the object whose signal we are listening to

 

sigName

the name of the signal we are listening to

 

callback

the callback function

 

bind

(optional) the object to bind the function to. Leave empty for the owner of the SignalManager (which has no side effects if you don't need to bind at all).

 

force

whether to connect again even if it is connected

 

isConnected ()


isConnected (string     sigName,
             Object     obj,
             function   callback);

This checks whether the signal sigName is connected. The optional arguments obj and callback can be used to specify what signals in particular we want to know. Note that when you supply callBack, you usually want to supply obj as well, since two different objects can connect to the same signal with the same callback.

This is functionally equivalent to (and implemented as)

1
this.getSignals(arguments).length > 0);

Parameters

sigName

the signal we care about

 

obj

(optional) the object we care about, or leave empty if we don't care about which object it is

 

callback

(optional) the callback function we care about, or leave empty if we don't care about what callback is connected

 

Returns

Whether the signal is connected


getSignals ()

Array
getSignals (string     sigName,
            Object     obj,
            function   callback);

This returns the list of all signals that matches the description provided. Each signal is represented by an array in the form [signalName, object, callback, signalId].

Parameters

sigName

the signal we care about

 

obj

(optional) the object we care about, or leave empty if we don't care about which object it is

 

callback

(optional) the callback function we care about, or leave empty if we don't care about what callback is connected

 

Returns

The list of signals


disconnect ()


disconnect (string     sigName,
            Object     obj,
            function   callback);

This disconnects all signals named sigName. By default, it disconnects the signal on all objects, but can be fine-tuned with the optional obj and callback arguments.

This function will do nothing if no such signal is connected, the object no longer exists, or the signal is somehow already disconnected. So checks need not be performed before calling this function.

Parameters

sigName

the signal we care about

 

obj

(optional) the object we care about, or leave empty if we don't care about which object it is

 

callback

(optional) the callback function we care about, or leave empty if we don't care about what callback is connected

 

disconnectAllSignals ()


disconnectAllSignals ();

Disconnects all signals managed by the SignalManager. This is useful in the destroy function of objects.

Property Details

The “_object” property

  “_object”                  Object

The object owning the SignalManager. All callbacks are binded to _object unless otherwise specified.


The “_storage” property

  “_storage”                 Array

An array that stores all the connected signals. Each signal is stored as an array in the form [signalName, object, callback, signalId].