jointjs/docs/src/joint/api/dia/Paper/events.html

JavaScript diagramming library

<p>The following list contains events that you can react on in a paper:</p>
<table>
  <tr>
    <th>pointerdblclick</th>
    <td>
      <p>Triggered when pointer is double-clicked on a target (a <code>dblclick</code> event is detected).</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:pointerdblclick</th>
          <td>Triggered when pointer is double-clicked on a cell.</td>
        </tr>
        <tr>
          <th>link:pointerdblclick</th>
          <td>Triggered when pointer is double-clicked on a link.</td>
        </tr>
        <tr>
          <th>element:pointerdblclick</th>
          <td>Triggered when pointer is double-clicked on an element.</td>
        </tr>
        <tr>
          <th>blank:pointerdblclick</th>
          <td>
            <p>Triggered when pointer is double-clicked on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>pointerclick</th>
    <td>
      <p>Triggered when pointer is clicked on a target without pointer movement (a <code>click</code> or <code>touchend</code> event is detected). Occurs alongside <code>pointerdown</code> and <code>pointerup</code> events.</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:pointerclick</th>
          <td>Triggered when pointer is clicked on a cell.</td>
        </tr>
        <tr>
          <th>link:pointerclick</th>
          <td>Triggered when pointer is clicked on a link. </td>
        </tr>
        <tr>
          <th>element:pointerclick</th>
          <td>Triggered when pointer is clicked on an element.</td>
        </tr>
        <tr>
          <th>blank:pointerclick</th>
          <td>
            <p>Triggered when pointer is clicked on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>contextmenu</th>
    <td>
      <p>Triggered when pointer is right-clicked on a target (a <code>contextmenu</code> event is detected).</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:contextmenu</th>
          <td>Triggered when pointer is right-clicked on a cell.</td>
        </tr>
        <tr>
          <th>link:contextmenu</th>
          <td>Triggered when pointer is right-clicked on a link.</td>
        </tr>
        <tr>
          <th>element:contextmenu</th>
          <td>Triggered when pointer is right-clicked on an element.</td>
        </tr>
        <tr>
          <th>blank:contextmenu</th>
          <td>
            <p>Triggered when pointer is right-clicked on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>pointerdown</th>
    <td>
      <p>Triggered when pointer is pressed down on a target (a <code>mousedown</code> or <code>touchstart</code> event is detected). The paper also starts delegating respective <code>pointermove</code> and <code>pointerup</code> events (including their touch counterparts; see below).</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:pointerdown</th>
          <td>Triggered when pointer is pressed down on a cell.</td>
        </tr>
        <tr>
          <th>link:pointerdown</th>
          <td>Triggered when pointer is pressed down on a link.</td>
        </tr>
        <tr>
          <th>element:pointerdown</th>
          <td>Triggered when pointer is pressed down on an element.</td>
        </tr>
        <tr>
          <th>blank:pointerdown</th>
          <td>
            <p>Triggered when pointer is pressed down on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>pointermove</th>
    <td>
      <p>Triggered when pointer is moved over a target while pressed down (a <code>mousemove</code> or <code>touchmove</code> event is detected).</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:pointermove</th>
          <td>Triggered when pointer is moved over a cell.</td>
        </tr>
        <tr>
          <th>link:pointermove</th>
          <td>Triggered when pointer is moved over a link.</td>
        </tr>
        <tr>
          <th>element:pointermove</th>
          <td>Triggered when pointer is moved over an element.</td>
        </tr>
        <tr>
          <th>blank:pointermove</th>
          <td>
            <p>Triggered when pointer is moved over the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>pointerup</th>
    <td>
      <p>Triggered when pointer is released on a target after being pressed down (a <code>mouseup</code> or <code>touchend</code> event is detected).</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:pointerup</th>
          <td>Triggered when pointer is released on a cell.</td>
        </tr>
        <tr>
          <th>link:pointerup</th>
          <td>Triggered when pointer is relased on a link.</td>
        </tr>
        <tr>
          <th>element:pointerup</th>
          <td>Triggered when pointer is released on an element.</td>
        </tr>
        <tr>
          <th>blank:pointerup</th>
          <td>
            <p>Triggered when pointer is released on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code> and <code>y</code> as arguments.</p>
          </td>
        </tr>
      </table>
      <p>Calling <code>evt.stopPropagation()</code> prevents triggering a subsequent <code>pointerclick</code> event.</p>
    </td>
  </tr>
  <tr>
    <th>mouseover</th>
    <td>
      <p>Triggered when pointer begins to hover directly over a target.</p>
      <p>The callback function is passed <code>cellView</code> and <code>evt</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:mouseover</th>
          <td>Triggered when pointer begins to hover directly over a cell.</td>
        </tr>
        <tr>
          <th>link:mouseover</th>
          <td>Triggered when pointer begins to hover directly over a link.</td>
        </tr>
        <tr>
          <th>element:mouseover</th>
          <td>Triggered when pointer begins to hover directly over an element.</td>
        </tr>
        <tr>
          <th>blank:mouseover</th>
          <td>
            <p>Triggered when pointer begins to hover over the <code>svg</code> element of the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code> as argument.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>mouseout</th>
    <td>
      <p>Triggered when pointer ceases to hover directly over a target.</p>
      <p>The callback function is passed <code>cellView</code> and <code>evt</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:mouseout</th>
          <td>Triggered when pointer ceases to hover directly over a cell.</td>
        </tr>
        <tr>
          <th>link:mouseout</th>
          <td>Triggered when pointer ceases to hover directly over a link.</td>
        </tr>
        <tr>
          <th>element:mouseout</th>
          <td>Triggered when pointer ceases to hover directly over an element.</td>
        </tr>
        <tr>
          <th>blank:mouseout</th>
          <td>
            <p>Triggered when pointer ceases to hover over the <code>svg</code> element of the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code> as argument.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>mouseenter</th>
    <td>
      <p>Triggered when pointer enters the area above a target.</p>
      <p>The callback function is passed <code>cellView</code> and <code>evt</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:mouseenter</th>
          <td>Triggered when pointer enters the area above a cell.</td>
        </tr>
        <tr>
          <th>link:mouseenter</th>
          <td>Triggered when pointer enters the area above a link.</td>
        </tr>
        <tr>
          <th>element:mouseenter</th>
          <td>Triggered when pointer enters the area above an element.</td>
        </tr>
        <tr>
          <th>paper:mouseenter</th>
          <td>
            <p>Triggered when pointer enters the area of the paper (including paper border, if present).</p>
            <p>The callback function is passed <code>evt</code> as argument.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>mouseleave</th>
    <td>
      <p>Triggered when pointer leaves the area above a target.</p>
      <p>The callback function is passed <code>cellView</code> and <code>evt</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:mouseleave</th>
          <td>Triggered when pointer leaves the area above a cell.</td>
        </tr>
        <tr>
          <th>link:mouseleave</th>
          <td>Triggered when pointer leaves the area above a link.</td>
        </tr>
        <tr>
          <th>element:mouseleave</th>
          <td>Triggered when pointer leaves the area above an element.</td>
        </tr>
        <tr>
          <th>paper:mouseleave</th>
          <td>
            <p>Triggered when pointer leaves the area of the paper (including paper border, if present).</p>
            <p>The callback function is passed <code>evt</code> as argument.</td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>mousewheel</th>
    <td>
      <p>Triggered when mouse wheel is rotated while pointer is on a target.</p>
      <p>The callback function is passed <code>cellView</code>, <code>evt</code>, <code>x</code>, <code>y</code> and <code>delta</code> as arguments.</p>
      <table>
        <tr>
          <th>cell:mousewheel</th>
          <td>Triggered when mouse wheel is rotated while the pointer is on a cell.</td>
        </tr>
        <tr>
          <th>link:mousewheel</th>
          <td>Triggered when mouse wheel is rotated while the pointer is on a link.</td>
        </tr>
        <tr>
          <th>element:mousewheel</th>
          <td>Triggered when mouse wheel is rotated while the pointer is on an element.</td>
        </tr>
        <tr>
          <th>blank:mousewheel</th>
          <td>
            <p>Triggered when mouse wheel is rotated while the pointer is on the paper outside any cell.</p>
            <p>The callback function is passed <code>evt</code>, <code>x</code>, <code>y</code> and <code>delta</code> as arguments.</p>
          </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr>
    <th>magnet</th>
      <td>
        <p>Triggered when interacting with a magnet target.</p>
        <p>The callback function is passed <code>elementView</code>, <code>evt</code>, <code>magnetSVGElement</code>, <code>x</code>, <code>y</code> as arguments.</p>
        <table>
          <tr>
            <th>element:magnet:pointerclick</th>
            <td>Triggered when pointer is clicked on an element magnet and no link was created yet from this magnet (controlled by <a href="#dia.Paper.prototype.options.magnetThreshold">magnetThreshold</a> option). Calling <code>evt.stopPropagation()</code> prevents triggering <code>cell:pointerclick</code> and <code>element:pointerclick</code> events.</td>
          </tr>
          <tr>
            <th>element:magnet:pointerdblclick</th>
            <td>Triggered when pointer is double-clicked on an element magnet. Calling <code>evt.stopPropagation()</code> prevents triggering <code>cell:pointerdblclick</code> and <code>element:pointerdblclick</code> events.</td>
          </tr>
          <tr>
            <th>element:magnet:contextmenu</th>
            <td>Triggered when pointer is right-clicked on an element magnet. Calling <code>evt.stopPropagation()</code> prevents triggering <code>cell:contextmenu</code> and <code>element:contextmenu</code> events.<td>
          </tr>
        </table>
      </td>
    </tr>
  <tr>
    <th>cell:highlight</th>
    <td>
      <p>Triggered when the <code>cellView.highlight</code> <a href="#dia.CellView.prototype.highlight">method</a> is called on a link or element view.</p>
      <p>The callback function is invoked with the following arguments:</p>
      <ul>
        <li><b>cellView</b> - highlighted CellView</li>
        <li><b>node</b> - highlighted node (SVGElement) of the CellView</li>
        <li><b>options</b> - options used when <code>cellView.highlight(node, options)</code> was called. The <code>type</code> property is added to the option object and specifies what type of <a href="#dia.Paper.prototype.options.highlighting">highlighting interactions</a> caused the highlight.</li>
      </ul>
      <pre><code>// Disable built-in highlighting
paper.options.highlighting = false;
// Handle each type of the highlight manually
paper.on('cell:highlight', (cellView, node, options) => {
  switch (options.type) {
    case: joint.dia.CellView.Highlighting.CONNECTING: {
      joint.highlighters.stroke.add(cellView, node, 'id1', { attrs: { 'stroke': 'blue' }});
      break;
    }
    case: joint.dia.CellView.Highlighting.EMBEDDING: {
      joint.highlighters.stroke.add(cellView, node, 'id2', { attrs: { 'stroke': 'red' }});
      break;
    }
    default: {
      joint.highlighters.stroke.add(cellView, node, 'id3');
      break;
    }
  }
});</code></pre>
    </td>
  </tr>
  <tr>
    <th>cell:unhighlight</th>
    <td>
      <p>Triggered when the <code>cellView.unhighlight</code> <a href="#dia.CellView.prototype.unhighlight">method</a> is called on a link or element view.</p>
      <p>The callback function is invoked with the following arguments:</p>
      <ul>
        <li><b>cellView</b> - highlighted CellView</li>
        <li><b>node</b> - highlighted node (SVGElement) of the CellView</li>
        <li><b>options</b> - options used when <code>cellView.unhighlight(node, options)</code> was called. The <code>type</code> property is added to the option object and specifies what type of <a href="#dia.Paper.prototype.options.highlighting">highlighting interactions</a> caused the unhighlight.</li>
      </ul>
      <pre><code>// Disable built-in highlighting
paper.options.highlighting = false;
// Handle each type of the highlight manually
paper.on('cell:unhighlight', (cellView, _node, options) => {
  switch (options.type) {
    case: joint.dia.CellView.Highlighting.CONNECTING: {
      joint.dia.Highlighter.remove(cellView, 'id1');
      break;
    }
    case: joint.dia.CellView.Highlighting.EMBEDDING: {
      joint.dia.Highlighter.remove(cellView, 'id2');
      break;
    }
    default: {
      joint.dia.Highlighter.remove(cellView, 'id3');
      break;
    }
  }
});</code></pre>
    </td>
  </tr>
  <tr>
    <th>cell:highlight:invalid</th>
    <td>
      <p>Triggered when a highlighter makes an attempt to highlight a node, that doesn't exist on the CellView (e.g. a port was highlighted and now it is removed).</p>
      <p>The callback function is passed <code>cellView</code>, <code>highlighterId</code> and <code>highlighter</code> as arguments.</p>
      <pre><code>paper.on('cell:highlight:invalid', (cellView, id) => {
  // Remove the invalid highlighter
  joint.dia.HighlighterView.remove(cellView, id);
});
element1.addPort({ id: 'port1' });
const elementView1 = element1.findView(paper);
const highlighter1 = joint.highlighters.mask.add(elementView1, { port: 'port1' }, 'highlighter-id'));
// The following line will trigger the event with (elementView1, 'highlighter-id', highlighter1) arguments.
element1.removePorts();</code></pre>
    </td>
  </tr>
  <tr>
    <th>link:connect</th>
    <td>
      <p>Triggered when a link is connected to a cell. The event is triggered after the user reconnects a link.</p>
      <p>The callback function is passed <code>linkView</code>, <code>evt</code>, <code>elementViewConnected</code>, <code>magnet</code> and <code>arrowhead</code> as arguments.</p>
    </td>
  </tr>
  <tr>
    <th>link:disconnect</th>
    <td>
      <p>Triggered when a link is disconnected from a cell. The event is triggered after the user reconnects a link.</p>
      <p>The callback function is passed <code>linkView</code>, <code>evt</code>, <code>elementViewDisconnected</code>, <code>magnet</code> and <code>arrowhead</code> as arguments.</p>
    </td>
  </tr>
  <tr>
    <th>link:snap:connect</th>
    <td>
      <p>Triggered when a link is connected to a cell. The event (or multiple events) can be triggered while the user is reconnecting a link and <a href="#dia.Paper.prototype.options.snapLinks">snapLinks</a> option is enabled.</p>
      <p>The callback function is passed <code>linkView</code>, <code>evt</code>, <code>elementViewConnected</code>, <code>magnet</code> and <code>arrowhead</code> as arguments.</p>
    </td>
  </tr>
  <tr>
    <th>link:snap:disconnect</th>
    <td>
      <p>Triggered when a link is disconnected from a cell. The event (or multiple events) can be triggered while the user is reconnecting a link and <a href="#dia.Paper.prototype.options.snapLinks">snapLinks</a> option is enabled.</p>
      <p>The callback function is passed <code>linkView</code>, <code>evt</code>, <code>elementViewDisconnected</code>, <code>magnet</code> and <code>arrowhead</code> as arguments.</p>
    </td>
  </tr>
  <tr>
    <th>render:done</th>
    <td>
      <p>Triggered when all scheduled updates are done (i.e. all scheduled batches have finished).</p>
    </td>
  </tr>
  <tr>
    <th>[custom]</th>
    <td>
      <p>Custom cell event can be triggered on pointerdown with <a href="#dia.attributes.event">Event</a> attribute. Calling <code>evt.stopPropagation()</code> prevents triggering all subsequent events.</p>
    </td>
  </tr>
</table>

<p>An example of a simple <code>blank:pointerdown</code> event listener:</p>

<pre><code>paper.on('blank:pointerdown', function(evt, x, y) {
  alert('pointerdown on a blank area in the paper.')
})</code></pre>

<p>Consecutive <code>pointerdown</code>, <code>pointermove</code> and <code>pointerup</code> events can share information through the <code>evt.data</code> object:</p>

<pre><code>// Create a new link by dragging
paper.on({
  'blank:pointerdown': function(evt, x, y) {
    var link = new joint.dia.Link();
    link.set('source', { x: x, y: y });
    link.set('target', { x: x, y: y });
    link.addTo(this.model);
    evt.data = { link: link, x: x, y: y };
  },
  'blank:pointermove': function(evt, x, y) {
    evt.data.link.set('target', { x: x, y: y });
  },
  'blank:pointerup': function(evt) {
    var target = evt.data.link.get('target');
    if (evt.data.x === target.x && evt.data.y === target.y) {
        // remove zero-length links
        evt.data.link.remove();
    }
  }
});</code></pre>