SignalManager.SignalManager: Cinnamon Javascript Reference Manual

## SignalManager.SignalManager SignalManager.SignalManager — A convenience object for managing signals |

## Functions

| _init ()
| connect ()
| isConnected ()
Array | getSignals ()
| disconnect ()
| disconnectAllSignals ()

## 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]`.