All versions of this documentation
X

User interactions API Download code

Basics

Ogma has a built-in system of events and interaction states to make your work scenarios easier. It also provides tools for convenient nodes selection and basic state management.

States/Mouse events

You can subscribe to basic mouse/touch interactions on nodes and edges to define your scenarios.

Click

ogma.events.onClick(function(evt) { // subscribe to click events
  if (evt.target === null) { // you have clicked on the background
    // you can use the click position to coordinate your UI, move nodes etc.
    console.log('clicked on background at coordinates', evt.x, evt.y);
  } else if (evt.target.isNode) { // you have clicked on the node
    console.log('clicked on a node with id', evt.target.getId());

    // show the context menu for a particular node at the
    // calculated screen coordinate
    var position = ogma.view.graphToScreenCoordinates({ x: evt.x, y: evt.y });

    // trigger a user-defined function to show/hide UI,
    // in this case - a context menu
    showContextMenu(evt.target, position.x, position.y);
  } else { // it's an edge
    var edge = evt.target;
    console.log('clicked on an edge between ', edge.getSource().getId(), ' and', edge.getTarget().getId());
  }
});

Right click

You can also make use of the additional mouse events, such as secondary button, by performing a check in the onClick event handler

var currentNode;
ogma.events.onClick(function(evt) {
  var target = evt.target;
  // check for right click and raise a context menu with the items
  // depending on what is currently selected
  if (evt.button === 'right' && target && target.isNode) {
    var selected = ogma.getSelectedNodes();
    var group = false;

    // different items for menu for group or a single node
    if (selected.includes(target)) {
      currentNode = selected;
      group = true;
    } else {
      currentNode = target;
    }

    // get screen coodinates to position and raise the context menu
    var position = ogma.view.graphToScreenCoordinates(target.getPosition());

    // group flag is used to decide which actions to make available
    showMenu(position.x, position.y, group);
  }
});

Hover elements

Hovering elements follows the same scheme, you have to put your logic in the handler depending on what was hovered. You can also use helper function ogma.getHoveredElement() to get the element under the pointer.

// get the container to show information
var hoveredContainer = document.getElementById('hovered-nodes');
ogma.events.onMouseMove(function(evt) {
  var hovered = ogma.getHoveredElement();
  if (hovered && hovered.isNode) { // element is hovered and it's a node
    // show information about it in the UI
    var color = hovered.getAttribute('color');
    var text  = hovered.getAttribute('text');
    hoveredContainer.innerHTML =
      '<span class="node" style="background-color: ' + color + '">' +
                text + '</span>';
  } else {
    hoveredContainer.innerHTML = '';
  }
});

Drag elements

Dragging nodes is a built-in interaction of ogma that allows re-positioning of the nodes using your mouse or touch screen. You can subscribe for events of dragStart, dragProgress and dragEnd and read the information about the elements being dragged and their current positions. Oftten you would need to add or change visual styles for nodes and edges that you interact with, you can take a look at styling API tutorial to learn how you can use styles and classes in the CSS-like way.

// 'dragged' is a built-in class for the dragged nodes
ogma.events.onNodeDragStart(function(evt) {
  console.log('Started dragging', evt.nodes.size, 'nodes');
  // add visual style to the nodes that are not affected
  var nodes = evt.nodes;
  nodes.addClass('dragged');
  nodes.inverse().addClass('static');
});
ogma.events.onNodeDragEnd(function(evt) {
  var nodes = evt.nodes;
  nodes.removeClass('dragged');
  // reset visual style for the nodes that are not affected
  nodes.inverse().removeClass('static');
});

Selection

API

Selection can be done programmatically, using the API:

ogma.getNodes(['n1', 'n2', 'n3']).setSelected(true);
console.log(ogma.getSelectedNodes().getId()); // ['n1', 'n2', 'n3']
ogma.getSelectedNodes().setSelected(false);
console.log(ogma.getSelectedNodes().getId()); // []

You may find useful the methods for selection inversion, i.e. to retrieve the elements that are not selected:

ogma.getNonSelectedNodes(); // all nodes minus the selected ones selected

// these 3 lines of code will invert your selection
var selected = ogma.getSelectedNodes();
ogma.getNonSelectedNodes().setSelected(true);
selected.setSelected(false);

Lasso tool

Lasso tool allows selecting the nodes by freehand drawing an outline around them:

// subscribe to selection change event, it will be triggered once
// lasso selection is done
ogma.events.onNodesSelected(function() {
  console.log(ogma.getSelectedNodes().getId()); // ['id1', 'id2', ...]
});
ogma.tools.lasso.enable(); // enables lasso
// perform some freehand selection

Rectangle selection tool

Sometimes it is convenient to use a rectangular selection for the nodes, also it is a more familiar tool for the novice users and is used in a number of popular graphical redactors.

// subscribe to selection change event, it will be triggered once
// rectangle selection is done
ogma.events.onNodesSelected(function() {
  console.log(ogma.getSelectedNodes().getId()); // ['id1', 'id2', ...]
});
// switch rectangle select on drag start with the 'ctrl' key pressed
ogma.events.onDragStart(function () {
  if (ogma.keyboard.isKeyPressed('ctrl')) {
    ogma.tools.rectangleSelect.enable();
  }
});

Keyboards events

Ogma allows you to subscribe to keyboard events in order to trigger custom behavior or actions. For instance, you can assign a keyboard shortcut to call one of the tools:

function toggleLasso() {
  if (ogma.tools.lasso.enabled()) {
    ogma.tools.lasso.disable();
  } else  {
    ogma.tools.lasso.enable();
  }
}
ogma.events.onKeyPress('l', toggleLasso); // toggles lasso tool on/off

// '+' and '-' keys are used to zoom in and out with a short animation
ogma.events.onKeyPress('+', function() {
    ogma.view.zoomIn({ duration: 200 });
  })
  .onKeyPress('-', function() {
    ogma.view.zoomOut({ duration: 200 });
  });

Graph events end methods.

Ogma triggers several events that can be useful to assign custom interactions to. These can include notifications, stats or UI feedback.

For instance, you can get notified on nodesAdded, nodesRemoved events to show information about your graph:

// shows graph size stats
function showStats() {
  document.getElementById('stats').innerHTML =
    ogma.getNodes().size + ' nodes, ' + ogma.getEdges().size + 'edges';
}
ogma.events
  .onEdgesAdded(showStats)
  .onNodesAdded(showStats)
  .onNodesRemoved(showStats);

There are events that can allow you to listen to the viewport changes, to synchronize the position with your UI elements (tooltips, additional graphs and charts).

onDragStart, onDragProgress, onDragEnd, onZoomStart, onZoomProgress, onZoomEnd, can be used to synchronise additional graphics with the position and scale of ogma viewer. viewChanged is triggered with a delay after both zooming and panning are complete.

You can find full documentation on these and more events in the "Events" section.