Skip to content
This repository has been archived by the owner on Jul 18, 2022. It is now read-only.

Messages API

Jump to bottom
Benjamin Bach edited this page Mar 8, 2022 · 8 revisions

Messages in networkcube are send between visualizations to notify them about user interactions. Whatever a user does in one view can get propagated to any other view in your browser, via a message. The possible messages are listed below. Most of the messages are send automatically when, e.g. a visualization triggers the selection of a node via networkcube.selection('add', {nodes:[myNodesHere]}).

In order to receive messages, a visualization must either implement the default listener (triggered for every message), or a specific listener per event type. If there is a specific listener, the default listener is not invoked.

networkcube.setDefaultEventListener(myCallBack); // default listener
networkcube.addEventListener('timeRange', callBack); // specific listener.

When a networkcube instance in another view receives a message, such as a selection, it updates the data model accordingly. All the visualization has to do is to update the visual states of the objects, based on the information in the data model.

Messages

Most messages require some data elements to be passed between views/visualziations. However, as each visualization sits in its own window, tab, or iFrame only JSON objects can be communicated. Networkcube runs an instance of a DynamicNetwork in each visualization and consequently messages communicate indices of data objects. The messenger serializes data objects into its ids, and when receiving a messages, deserializes the ids to objects. The process of serialization and deserialization is transparent to the user.

Data objects are passed to messages via the ElementCompound structure:

class ElementCompund{
    nodes:networkcube.Node[],
    links:networkcube.Link[],
    nodePairs:networkcube.NodePair[],
    times:networkcube.Time[],
    locations:networkcube.Location[],
}

You do not have to create the entire TypeScript object but can specify only the fields you need:

var elements = {nodes: [n1, n2], links: [l1, l2, l3]}

Highlight Message

To highlight nodes, links, or any other data object, call one of the following methods in your visualizations. A corresponding highlight-message is propagated to all views in your browser.

    networkcube.highlight(action:string, compound:ElementCompound, params?:any);

The action argument specifies ''what happens'' to the set of elements specified in the elementCompound. In the below examples, any highlighting is temporary.

  • add the passed elements to the currently highlighted elements. Elements already selected are ignored.
  • remove the passed elements from the currently highlighted elements.
  • set the passed elements as uniquely highlighted, i.e. de-highlighted all other elements.
  • reset resets any highlighted element.

With the below examples, any highligting is permanent. Both sorts of highlighting are independent.

  • addFreeze the passed elements to the currently highlighted elements. Elements already selected are ignored.
  • removeFreeze the passed elements from the currently highlighted elements.
  • setFreeze the passed elements as uniquely highlighted, i.e. de-highlighted all other elements.
  • resetFreeze resets any highlighted element.

To reset all data objects of a certain type (node, link, time, location, nodepair, time):

windows.vc.main.highlight('reset')

or

windows.vc.main.highlight('resetFreeze')

The handler for the highlight event is:

networkworkcube.addEventListener('highlight', callBack)

The highlighted elements are in the message:

m.idCompound.nodes
m.idCompound.links
...

See here for an example on highlighting.

Selection Message

To highlight nodes, links, or any other data object, call one of the following methods in your visualizations. A corresponding highlight-message is propagated to all views in your browser.

    networkcube.selection(action:string, compound:ElementCompound, selectionId?:number);

The action argument specifies ''what happens'' to the set of elements specified in the elementCompound.

  • add the passed elements to the currently selected elements. Elements already selected are ignored.
  • remove the passed elements from the currently selected elements.
  • set the passed elements as uniquely selected, i.e. deselects all other elements.

The selectionId specifies a pointer to a Selection objects. Selection objects are explained in the section Selections.

The handler for the selection event is:

networkworkcube.addEventListener('selection', callBack)

Time Range Message

A Time Range message indicates that the user has changed a time range selection somewhere in a view, e.g. on a time range slider. A time range change is triggered by:

networkcube.timeRange(start:Time, end:Time, propagate?:boolean)

start and end indicate the time range.

The propagate flag indicates whether the message is propagated to other views. The default is true. However, changing the time range can cause other visualizations to start time-intensive queries.

The handler for time events is:

networkcube.addEventListener('timeRange', callBack(m))

A time range message contains the following fields: *startId:number *endId:number

Create/Delete/Set Selection Message

This message creates a Selection. More on selections in the Selection Section.

A selection is created/deleted/set as follows:

createSelection(type:string, name:string);
deleteSelection(selection:Selection);
setCurrentSelection(selection:Selection);

With a selection name and the types of objects it holds (node, link, time, nodePair, location).

The respective handlers are:

networkcube.addEventListener('createSelection', callBack(m))
networkcube.addEventListener('deleteSelection', callBack(m))
networkcube.addEventListener('setCurrentSelectionId', callBack(m))

The passed message contains:

  • the selection id.

To create, e.g., a selection for nodes and add some nodes with a specific color, do this:

var s:Selection = messenger.createSelection('node', 'Cluster 1')
messenger.setSelectionColor(s,'#f00');
messenger.selection('add', {nodes: [my-nodes-here]}, s.id);```

## Set Selection Color, Visibility, and Priority 

```typescript
// whether or not to color elements of this selection
showSelectionColor(selection:Selection, showColor:boolean); 
// whether or not to show elements in this selection
filterSelection(selection:Selection, filter:boolean);
// whether or not to show elements of this selection
swapPriority(s1:Selection, s2:Selection);
// change selection color
setSelectionColor(selection:Selection, color:String);

Handlers are

networkcube.addEventListener('selectionColoring', callBack(m))
networkcube.addEventListener('selectionFilter', callBack(m))
networkcube.addEventListener('selectionPriority', callBack(m))
networkcube.addEventListener('setSelectionColor', callBack(m))

Search Message

Propagates a the results of a search query.

networkcube.searh(term:string, type?:string)

The result messages contain an IdCompound of the retrieved elements matching the search query.

networkcube.addEventListener('searchResult', callBack(m))

User Specific Messages

An arbitrary message, carrying an arbitrary object is send by

networkcube.sendMessage(messageType:string, body:Object)

The respective handler is registered bye

networkcube.addEventListener(messageType, callBack(m))
Clone this wiki locally