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 passed <code>cellView</code> and <code>el</code> as arguments.</p>
      <p>The default handler method adds the <code data-lang="css">"highlighted"</code> CSS class to the cell, so that it can be targeted in user stylesheets. To use a different method for highlighting cells, first unregister the default handler with <code>paper.off('cell:highlight')</code> and then register a custom handler with <code>paper.on('cell:highlight', myHandler)</code>.</p>
      <p>This method is also called automatically, in two situations. First, if the user reconnects a link and the connection is valid as determined by the <code>paper.options.validateConnection</code> <a href="#dia.Paper.prototype.options.validateConnection">method</a>. Second, if <a href="#dia.Paper.prototype.options.embeddingMode">embedding mode</a> is enabled on the paper and dragged element is above another element it can be dropped onto as determined by the <code>paper.options.validateEmbedding</code> <a href="#dia.Paper.prototype.options.validateEmbedding">method</a>.</p>
    </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 passed <code>cellView</code> and <code>el</code> as arguments.</p>
      <p>The default handler method removes the <code data-lang="css">"highlighted"</code> CSS class from the cell. To use a different method, first unregister the default handler with <code>paper.off('cell:unhighlight')</code> and then register a custom handler with <code>paper.on('cell:unhighlight', myHandler)</code>.</p>
      <p>It is important to note that if a cell was highlighted using custom options, those exact same options must be provided to the unhighlight handler.</p>
    </td>
  </tr>
  <tr>
    <th>link:connect</th>
    <td>
      <p>Triggered when a link is connected to a cell.</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.</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 on <a href="#dia.Paper.prototype.options.async"><code>async</code></a> papers 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>