## Events

jsPlumb supports binding to several different events on Connections, Endpoints and Overlays, and also on the jsPlumb object itself.

- jsPlumb Events
- Connection Events
- Endpoint Events
- Overlay Events
- Unbinding Events

### jsPlumb Events

To bind an to event on jsPlumb itself (or a jsPlumb instance), use `jsPlumb.bind(event, callback)`:

    jsPlumb.bind("connection", function(info) {
       .. update your model in here, maybe.
    });

These are the events you can bind to on the jsPlumb class:

- `connection` - notification a Connection was established.

The first argument to the callback is an object with the following properties:

    {
      connection         :     the new Connection.  you can register listeners on this etc.
      sourceId         :    id of the source element in the Connection
      targetId        :    id of the target element in the Connection
      source        :    the source element in the Connection
      target        :    the target element in the Connection
      sourceEndpoint    :    the source Endpoint in the Connection
      targetEndpoint    :    the targetEndpoint in the Connection
    }

The second argument is the original mouse event that caused the Connection, if any.

All of the source/target properties are actually available inside the Connection object, but - for one of those rubbish historical reasons - are provided separately because of a vagary of the `connectionDetached` callback, which is discussed below.

- `connectionDetached` - notification a Connection was detached.

As with `connection`, the first argument to the callback is an object with the following properties:

    {
      connection        :     the Connection that was detached.
      sourceId        :    id of the source element in the Connection <em>before it was detached</em>
      targetId        :    id of the target element in the Connection before it was detached
      source        :    the source element in the Connection before it was detached
      target        :    the target element in the Connection before it was detached
      sourceEndpoint    :    the source Endpoint in the Connection before it was detached
      targetEndpoint    :    the targetEndpoint in the Connection before it was detached
    }

The second argument is the original mouse event that caused the disconnection, if any.

As mentioned above, the `source`/`target` properties are provided separately from the Connection, because this event is fired whenever a Connection is either detached and abandoned, or detached from some Endpoint and attached to another. In the latter case, the Connection that is passed to this callback is in an indeterminate state (that is, the Endpoints are still in the state they are in when dragging, and do not reflect static reality), and so the `source`/`target` properties give you the real story.

- `connectionDrag` - notification an existing Connection is being dragged. The callback is passed the Connection. Note that when this event fires for a brand new Connection, the target of the Connection is a transient element that jsPlumb is using for dragging, and will be removed from the DOM when the Connection is subsequently either established or aborted.

- `connectionDragStop` - notification a Connection drag has stopped. This is only fired for existing Connections. The callback is passed the Connection that was just dragged.

- `click` - notification a Connection was clicked. The callback is passed the Connection and the original mouse event.

- `dblclick` - notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.

- `endpointClick` - notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.

- `endpointDblClick` - notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.

- `contextmenu` - a right-click on some given component. jsPlumb will report right clicks on both Connections and Endpoints; the callback is passed the component that received the right-click.

- `beforeDrop` This event is fired when a new or existing connection has been dropped. Your callback is passed a JS object with these fields:

                    <ul>
                        <li><strong>sourceId</strong> - the id of the source element in the connection</li>
                        <li><strong>targetId</strong> - the id of the target element in the connection</li>
                        <li><strong>scope</strong> - the scope of the connection</li>
                        <li><strong>connection</strong> - the actual Connection object.  You can access the 'endpoints' array in a Connection to get the Endpoints involved in the Connection, but be aware that when a Connection is being dragged, one of these Endpoints will always be a transient Endpoint that exists only for the life of the drag. To get the Endpoint on which the Connection is being dropped, use the `dropEndpoint` member.</li>
                        <li><strong>dropEndpoint</strong> - this is the actual Endpoint on which the Connection is being dropped.  This <strong>may be null</strong>, because it will not be set if the Connection is being dropped on an element on which makeTarget has been called. </li>
                    </ul>

If you return false (or nothing) from this callback, the new Connection is aborted and removed from the UI.

- `beforeDetach` This event is fired when a Connection is about to be detached, for whatever reason. Your callback function is passed the Connection that the user has just detached. Returning false from this interceptor aborts the Connection detach.

### Connection Events

To bind to an event on a Connection, you also use the `bind` method:

    var connection = jsPlumb.connect({source:"d1", target:"d2"});
    connection.bind("click", function(conn) {
        console.log("you clicked on ", conn);
    });

These are the Connection events to which you can bind a listener:

- `click` - notification a Connection was clicked. The callback is passed the Connection and the original mouse event.
- `dblclick` - notification a Connection was double-clicked. The callback is passed the Connection and the original mouse event.
- `contextmenu` - a right-click on the Connection. The callback is passed the Connection and the original event.
- `mouseenter` - notification the mouse entered the Connection's path. The callback is passed the Connection and the original mouse event.
- `mouseexit` - notification the mouse exited the Connection's. The callback is passed the Connection and the original mouse event.
- `mousedown` - notification the mouse button was pressed on the Connection's path. The callback is passed the Connection and the original mouse event.
- `mouseup` - notification the mouse button was released on the Connection's path. The callback is passed the Connection and the original mouse event.

### Endpoint Events

To bind to an event on a Endpoint, you again use the `bind` method:

    var endpoint = jsPlumb.addEndpoint("d1", { someOptions } );
    endpoint.bind("click", function(endpoint) {
        console.log("you clicked on ", endpoint);
    });

These are the Endpoint events to which you can bind a listener:

- `click` - notification an Endpoint was clicked. The callback is passed the Endpoint and the original mouse event.
- `dblclick` - notification an Endpoint was double-clicked. The callback is passed the Endpoint and the original mouse event.
- `contextmenu` - a right-click on the Endpoint. The callback is passed the Endpoint and the original event.
- `mouseenter` - notification the mouse entered the Endpoint. The callback is passed the Endpoint and the original mouse event.
- `mouseexit` - notification the mouse exited the Endpoint. The callback is passed the Endpoint and the original mouse event.
- `mousedown` - notification the mouse button was pressed on the Endpoint. The callback is passed the Connection and the original mouse event.
- `mouseup` - notification the mouse button was released on the Endpoint. The callback is passed the Connection and the original mouse event.
- `maxConnections` - notification the user tried to drop a Connection on an Endpoint that already has the maximum number of Connections. The callback is passed as first argument an object literal containing the Endpoint, the Connection the user tried to drop, and the value of maxConnections for the Endpoint, and as second argument the original mouse event.

### Overlay Events

Registering event listeners on an Overlay is a slightly different procedure - you provide them as arguments to the Overlay's constructor. This is because you never actually act on an Overlay object.

Here's how to register a click listener on an Overlay:

    jsPlumb.connect({
        source:"el1",
        target:"el2",
        overlays:[
          [ "Label", {
            events:{
              click:function(labelOverlay, originalEvent) {
                console.log("click on label overlay for :" + labelOverlay.component);
              }
            }
          }],
          [ "Diamond", {
            events:{
              dblclick:function(diamondOverlay, originalEvent) {
                console.log("double click on diamond overlay for : " + diamondOverlay.component);
              }
            }
          }]
        ]
      });

The related component for an Overlay is available to you as the `component` member of the Overlay.

Note that events registered on Diamond, Arrow or PlainArrow overlays will not fire with the Canvas renderer - they work only with the SVG and VML renderers.

### Unbinding Events

On the jsPlumb object and on Connections and Endpoints, you can use the `unbind` method to remove a listener. This method either takes the name of the event to unbind:

    jsPlumb.unbind("click");

...or no argument, meaning unbind all events:

    var e = jsPlumb.addEndpoint("someDiv");
    e.bind("click", function() { ... });
    e.bind("dblclick", function() { ... });

    ...

    e.unbind("click");