Differences between revisions 1 and 72 (spanning 71 versions)

Do you want to share your own code snippet?

Let us know! Email <samad.lotia@gladstone.ucsf.edu> to have your snippet included in this cookbook.

Contents

Do you want to share your own code snippet?
About the cookbook
How to use the cookbook?
The list of app examples in the cookbook
Trouble shooting
Recommendations
App Porting Hints
Questions, suggestions

About the cookbook

To help app developers to develop their own app, the Cytoscape developer team developed the cookbook, a collection of small apps. The cookbook could be used to

get your feet wet
find a template project to extend
find out how to do something in Cytoscape.

How to use the cookbook?

SVN repository: http://chianti.ucsd.edu/svn/core3/samples/trunk/

Steps:

Check out sample project from SVN repository with the above URL
Compile with mvn clean install
Copy the jar in the project target directory to Cytoscape installation: deploy directory
Start Cytoscape 3.0

The list of app examples in the cookbook

The list of sample apps is basically the same as in the cookbook for Cytoscape 2.X. They are mostly Cytoscape Bundle apps, but also include a few Simple apps. Some of them are,

Introduction

This tutorial will show some code snippets about how to use Cytoscape APIs on app development. Each feature is included in a sample app, which can serve as a starting point or template for new app developers. The code snippets can also be used as reference for experienced developers.

Cytoscape app is usually packaged in a jar file and deployed to the deploy directory of Cytoscape. When Cytoscape starts up and initializes, its app manager will look up all the apps in deploy directory.

There are two types of Cytoscape App, Bundle app and Simplified App. In this cook book, we provide sample for both types.

If app developer will share and publish their Apps, they are encouraged to submit their Apps to Cytoscape app store website at http://apps.cytoscape.org/ .

How to add a tabbed Panel to Control panel?

Here's how to add a tabbed panel to the control panel.

// Define a CytoPanel class
public class MyCytoPanel extends JPanel implements CytoPanelComponent {

    ...
    @Override
    public CytoPanelName getCytoPanelName() {
        return CytoPanelName.WEST;
    }
     ...
}

// In the start method of your CyActivator class:
//   Create an instance:
MyCytoPanel myPanel = new MyPanel();
//   Register it as a service:
registerService(bc,myCytoPanel,CytoPanelComponent.class, new Properties());

The source code of sample Apps can be find here.

How to add an image icon (menu item) to the toolbar?

// Define a CyAction class
public class AddImageIconAction extends AbstractCyAction {
        
    public AddImageIconAction(CySwingApplication desktopApp){
        ...
        ImageIcon icon = new ImageIcon(getClass().getResource("/images/tiger.jpg"));

        putValue(LARGE_ICON_KEY, icon);
       ...
    }

    public boolean isInToolBar() {
        return true;
    }
    ...
}

// In the start method of your CyActivator class:
//   Create an instance:
AddImageIconAction addImageIconAction = new AddImageIconAction(cytoscapeDesktopService);
//   Register it as a service:
registerService(bc,addImageIconAction,CyAction.class, new Properties());

The source code of sample Apps can be find here.

How to create a submenu?

// Define a CyAction class
public class Sample04 extends AbstractCyAction {
    ...
    public Sample04(CySwingApplication desktopApp){
        // Add a sub-menu item -- Apps->Sample04->sample04
        super("sample04...");
        setPreferredMenu("Apps.Sample04");
        //Specify the menuGravity value to put the menuItem in the desired place
        setMenuGravity(2.0f);
        ...
    }

// In the start method of your CyActivator class:
//   Create an instance:
Sample04 Sample04Action = new Sample04(cytoscapeDesktopService);
//   Register it as a service:
registerService(bc,Sample04Action,CyAction.class, new Properties());

The source code of sample Apps can be find here.

How to create, modify, and destroy a network, nodes, and edges?

To create a network, get a reference to the CyNetworkFactory service, and tell it to create a network. With the new network, nodes and edges can be created through the CyNetwork interface.

  // To get a reference of CyNetworkFactory at CyActivator class of the App
  CyNetworkFactory cyNetworkFactoryServiceRef = getService(bc,CyNetworkFactory.class);

...

  // To create a new network
  CyNetwork myNet = cnf.createNetwork();

...

  // Add two nodes to the network
  CyNode node1 = myNet.addNode();
  CyNode node2 = myNet.addNode();
                
  // set name for new nodes
  myNet.getDefaultNodeTable().getRow(node1.getSUID()).set("name", "Node1");
  myNet.getDefaultNodeTable().getRow(node2.getSUID()).set("name", "Node2");
                
  // Add an edge
  myNet.addEdge(node1, node2, true);

Destroying networks is done through the CyNetworkManager service.

First, in the start method of your CyActivator class:

  // Get a CyNetworkManager
  CyNetworkManager netMgr = getService(bc,CyNetworkManager.class);

Now you can use CyNetworkManager in your code:

  // Destroy a network with NetworkManager
  netMgr.destroyNetwork(myNet); 

The source code of sample Apps can be find here.

Getting node views for newly created nodes?

After creating a node and edge, this is how to get its view:

  CyNetworkView networkView = ...;
  CyNetwork network = networkView.getModel();
  CyEventHelper eventHelper = ...;
  CyNode newNode = network.addNode();
  network.getRow(newNode).set(CyNetwork.NAME, "New Node");
  eventHelper.flushPayloadEvents();
  View<CyNode> newNodeView = networkView.getNodeView(newNode);

After creating the node in CyNetwork, you have to call CyEventHelper's flushPayloadEvents so that the new node gets a node view. If flushPayloadEvents is not called, getNodeView may return null.

If you are creating a bunch of nodes at once, call flushPayloadEvents after you have finished creating all the nodes, not after each node is created. Example:

  CyNetworkView networkView = ...;
  CyNetwork network = networkView.getModel();
  CyEventHelper eventHelper = ...;
  
  for (int i = 1; i <= 100; i++) {
    CyNode node = network.addNode();
    network.getRow(newNode).set(CyNetwork.NAME, "Node " + i);
  }
  eventHelper.flushPayloadEvents();

How to create, modify, and destroy a network view?

To create a network, get a reference to the CyNetworkViewFactory service, and tell it to create a network view.

First, in the start method of your CyActivator class:

  // Get a CyNetworkViewFactory
  CyNetworkViewFactory cyNetworkViewFactoryServiceRef = getService(bc,CyNetworkViewFactory.class);

Now you can use CyNetworkViewFactory in your code:

  // Create a new network view
  CyNetworkView myView = cnvf.createNetworkView(myNet);

Destroying networks is done through the CyNetworkViewManager service.

First, in the start method of your CyActivator class:

  // get a CyNetworkViewManager
  CyNetworkViewManager cyNetworkViewManagerServiceRef = getService(bc,CyNetworkViewManager.class);

Now you can use CyNetworkViewManager in your code:

  // destroy a network view through NetworkViewManager
  networkViewManager.destroyNetworkView(myView);

The source code of sample Apps can be find here.

How to determine which nodes are currently selected on a network?

We can use CyTableUtil to get the list of selected nodes in a network

//Get the selected nodes
  List<CyNode> nodes = CyTableUtil.getNodesInState(myNetwork,"selected",true);

How to handle events from a network (and discuss each event type)?

To handle Cytoscape events, implement the listener interface and register it.

  // Define a class, which implements a listener interface
  public class MyListenerClass implements NetworkAddedListener {
    ....
    public void handleEvent(NetworkAddedEvent e){
        // do something here
    }
  }

In the start method of your CyActivator class:

  // Register the listener in the CyActivator class
  registerService(bc,myListenerClass, NetworkAddedListener.class, new Properties());

The source code of sample Apps can be find here.

How to change the background color of a view?

Network background color is changed as a _visual property_.

  // Set the background of current view to RED  
  view.setVisualProperty(BasicVisualLexicon.NETWORK_BACKGROUND_PAINT, Color.red);
  view.updateView(); 

The source code of sample Apps can be find here.

How to zoom a network view?

// Get the scale and adjust
double newScale = view.getVisualProperty(NETWORK_SCALE_FACTOR).doubleValue() * scale;
view.setVisualProperty(NETWORK_SCALE_FACTOR, newScale);
...     
view.updateView();

The source code of sample Apps can be find here.

How to load attribute data?

There are two step to load attribute to a table. (1) Create a global table and populate it. (2) Map the global table to specific table based on a key attribute, i.e. create virtual column for the table.

// Define a task
public class CreateTableTask extends AbstractTask {
    ....
    @Override
    public void run(TaskMonitor tm) throws IOException {
        // Step 1: create a new table
        CyTable table = tableFactory.createTable("MyAttrTable " + Integer.toString(numImports++), 
                                   "name", String.class, true, true);

        // create a column for the table
        String attributeNmae = "MyAttributeName"; 
        table.createColumn(attributeNmae, Integer.class, false);
                
        // Step 2: populate the table with some data
        String[] keys = {"YLL021W","YBR170C","YLR249W"}; //map to the the "name" column
        CyRow row = table.getRow(keys[0]);
        row.set(attributeNmae, new Integer(2));

        row = table.getRow(keys[1]);
        row.set(attributeNmae, new Integer(3));

        row = table.getRow(keys[2]);
        row.set(attributeNmae, new Integer(4));

        // We are loading node attribute
        Class<? extends CyTableEntry> type = CyNode.class;

        // Step 3: pass the new table to MapNetworkAttrTask
        super.insertTasksAfterCurrentTask( new MapNetworkAttrTask(type,table,netMgr,appMgr,rootNetworkManager) );
    }
    ....
}

The source code of sample Apps can be find here.

How to remove attributes?

1. get the CyTable through the network

    // case for Node table
    CyTable nodeTable = network.getDefaultNodeTable();

2. Find the column and delete it

    if(nodeTable.getColumn(columnName)!= null){
        nodeTable.deleteColumn(columnName);
    }   

The source code of sample Apps can be find here.

How to use a web service client?

First define a listener of web service client and register it as service -- WebServiceHelper. This class will keep tracker of web service clients available using a Map.

  public class WebServiceHelper {
  ...
        public void addWebServiceClient(final WebServiceClient newFactory,
                        final Map properties)
        {
                webserviceMap.put(newFactory, properties);
        }

        public void removeWebServiceClient(final WebServiceClient factory,
                        final Map properties)
        {
                webserviceMap.remove(factory);
        }
  ...
  }  

At running time, check if the needed service is available by looking at the map.

  Iterator<WebServiceClient> it = webserviceMap.keySet().iterator();
                
  while (it.hasNext()){
    WebServiceClient client = it.next();
    // Based on the serviceLocation, we can find if the client we are looking for is available
    System.out.println("WebService CLient client: DisplayName() is "+client.getDisplayName());
    System.out.println("WebService CLient client: ServiceLocation() is "+client.getServiceLocation());
    ....  
  }

If the needed client is found, then we can construct the query and execute the query through the API of the client.

How to write a web service client?

Step 1. Define a UI class for the setting of the client. This UI may listen to Cytoscape events

  public class MyWebserviceClientPanel extends JPanel implements ColumnCreatedListener, ColumnDeletedListener,
    SetCurrentNetworkListener {
  ...
}

Step 2. Define a client class, which must implement WebServiceClient and pass the UI class defined at previous step to the client. If UI is not defined, the default UI will be used.

  public class MyWebserviceClient extends AbstractWebServiceGUIClient implements TableImportWebServiceClient {
  ...
  }

Step 3. After the client is registered as service, the client can be find under File-->Import->Table-->Public databases...

How to use the VizMapper programmatically?

Cytosape provides services for using visual mapping programming. There services are VisualMappingManager, VisualStyleFactory and VisualMappingFunctionFactory. App should get references to these services in CyActivator class, the entry point of the app. We can create new visualStyle with VisualStyleFactory and create mapping function with VisualMappingFunctionFactory very easily. After a new visual style is created, it should register with the VisualMappingManger, in this way the new visual style will be available throughout Cytoscape.

  // To get references to services in CyActivator class
  VisualMappingManager vmmServiceRef = getService(bc,VisualMappingManager.class);
                
  VisualStyleFactory visualStyleFactoryServiceRef = getService(bc,VisualStyleFactory.class);
                
  VisualMappingFunctionFactory vmfFactoryC = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=continuous)");
  VisualMappingFunctionFactory vmfFactoryD = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=discrete)");
  VisualMappingFunctionFactory vmfFactoryP = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=passthrough)");


  // To create a new VisualStyle object and set the mapping function
  VisualStyle vs= this.visualStyleFactoryServiceRef.createVisualStyle("My visual style");


  //Use pass-through mapping
  String ctrAttrName1 = "SUID";
  PassthroughMapping pMapping = (PassthroughMapping) vmfFactoryP.createVisualMappingFunction(ctrAttrName1, String.class, attrForTest, BasicVisualLexicon.NODE_LABEL);

  vs.addVisualMappingFunction(pMapping);                        


  // Add the new style to the VisualMappingManager
  vmmServiceRef.addVisualStyle(vs);


  // Apply the visual style to a NetwokView
  vs.apply(myNetworkView);
  myNetworkView.updateView();

The source code of sample Apps can be find here.

How to apply a continuous color gradient to nodes according to their degree?

  
  // Set node color map to attribute "Degree"
  ContinuousMapping mapping = (ContinuousMapping)
                this.continuousMappingFactoryServiceRef.createVisualMappingFunction("Degree", Integer.class, BasicVisualLexicon.NODE_FILL_COLOR);

  // Define the points
  Double val1 = 2d;
  BoundaryRangeValues<Paint> brv1 = new BoundaryRangeValues<Paint>(Color.RED, Color.GREEN, Color.PINK);

  Double val2 = 12d;
  BoundaryRangeValues<Paint> brv2 = new BoundaryRangeValues<Paint>(Color.WHITE, Color.YELLOW, Color.BLACK);
                
  // Set the points
  mapping.addPoint(val1, brv1);
  mapping.addPoint(val2, brv2);

  // add the mapping to visual style            
  vs.addVisualMappingFunction(mapping); 

The source code of sample Apps can be find here.

How to load a visual properties file?

Cytoscape provide a service 'LoadVizmapFileTaskFactory' for loading visual styles definded in a property file.

  // get a reference to Cytoscape service -- LoadVizmapFileTaskFactory 
  LoadVizmapFileTaskFactory loadVizmapFileTaskFactory =  getService(bc,LoadVizmapFileTaskFactory.class);

  // Use the service to load visual style, 'f' is the File object to hold the visual properties 
  Set<VisualStyle> vsSet = loadVizmapFileTaskFactory.loadStyles(f);

How to get and set node coordinate positions?

Given a View<CyNode>, here's how to get its x and y coordinate positions:

View<CyNode> nodeView = ...;
Double x = nodeView.getVisualProperty(BasicVisualLexicon.NODE_X_LOCATION);
Double y = nodeView.getVisualProperty(BasicVisualLexicon.NODE_Y_LOCATION);

Here's how to set the x and y coordinate positions:

View<CyNode> nodeView = ...;
double x = ...;
double y = ...;
nodeView.setVisualProperty(BasicVisualLexicon.NODE_X_LOCATION, x);
nodeView.setVisualProperty(BasicVisualLexicon.NODE_Y_LOCATION, y);

How to write a layout algorithm?

First define a layout class, which implements CyLayoutAlgorithm interface or extends AbstractLayoutAlgorithm class. Then register the layout class as a service.

  // Define a layout class
  public class MyLayout extends AbstractLayoutAlgorithm {
    ...
  }


  // Define a layout task class
  public class MyLayoutTask extends AbstractLayoutTask {
    ...

    //Perform actual layout task
    final protected void doLayout(final TaskMonitor taskMonitor) {
      ...   
    }
    ...
  }


  // Register the layout class as a service in CyActivator class
  Properties myLayoutProps = new Properties();
  myLayoutProps.setProperty("preferredMenu","My Layouts");
  registerService(bc,myLayout,CyLayoutAlgorithm.class, myLayoutProps);

The source code of sample Apps can be find here.

How to write a Group Viewer?

   1 
   2

How to add components to the node view, edge view, and attribute browser context menus?

To add a context menu to a NodeView, define a class, which extends AbstractNodeViewTaskFactory, and register the NodeViewTaskFactory as service. We can add the title of menu item by setting the service property when we register the nodeViewTaskFactory.

To add context menu to the table browser, define a class, which extends AbstractTableCellTaskFactory. Create an instance and register it as service (Note register as TableCellTaskFactory).

  // Define a class MyNodeViewTaskFactory 
  public class MyNodeViewTaskFactory extends AbstractNodeViewTaskFactory {
    ...
  }


  // Register myNodeViewTaskFactory as a service in CyActivator
  Properties myNodeViewTaskFactoryProps = new Properties();
  myNodeViewTaskFactoryProps.setProperty("title","My context menu title");
  registerService(bc,myNodeViewTaskFactory,NodeViewTaskFactory.class, myNodeViewTaskFactoryProps);

The source code of sample Apps can be find here.

How to save/restore app states?

There are two events, which are important for saving/restoring App state. The two evetns are SessionAboutToBeSavedEvent and SessionLoadedEvent. App should implement the two listeners and register them.

  // Implements the session event listeners
  public class MyClass implements SessionAboutToBeSavedListener, SessionLoadedListener {

      // Save app state in a file
      public void handleEvent(SessionAboutToBeSavedEvent e){
          // save app state file "myAppStateFile"
          ...
      }

      // restore app state from a file
      public void handleEvent(SessionLoadedEvent e){

        if (e.getLoadedSession().getAppFileListMap() == null || e.getLoadedSession().getAppFileListMap().size() ==0){
            return;
        }       
        List<File> files = e.getLoadedSession().getAppFileListMap().get("myAppStateFile");
        ...
       }
  }
 

  // Register the two listeners in the CyActivator class
  registerService(bc,myClass,SessionAboutToBeSavedListener.class, new Properties());
  registerService(bc,myClass,SessionLoadedListener.class, new Properties());

The source code of sample Apps can be find here.

How to use the Cytoscape task monitor to show the progress of my job?

Get a Cytoscape service DialogTaskManager and execute the task through the taskManager.

  // Get a Cytoscape service 'DialogTaskManager' in CyActivator class
  DialogTaskManager dialogTaskManager = getService(bc, DialogTaskManager.class);


  // Define a task and set the progress in the run() method
  public class MyTask extends AbstractTask {
    ...
    public void run(final TaskMonitor taskMonitor) {
        // Give the task a title.
        taskMonitor.setTitle("My task");
        ...
        taskMonitor.setProgress(0.1);

        // do something here

        ...
        taskMonitor.setProgress(1.0);
  }


  // Execute the task through the TaskManager
  DialogTaskManager.execute(myTaskFactory);

The source code of sample Apps can be find here.

How to add new attribute functions via a Cytoscape App?

Here we will go through all the steps necessary to create a new built-in function IXOR(). The complete example code and can be downloaded from here. The easiest part is writing the actual plug-in class, which look similar to this:

  import org.cytoscape.equations.EquationCompiler;
  import org.cytoscape.equations.Interpreter;
  import org.cytoscape.equations.EquationParser;

  public class Sample23 {

        public Sample23(EquationCompiler eqCompilerRef, Interpreter interpreterRef){
                final EquationParser theParser = eqCompilerRef.getParser();
                theParser.registerFunction(new IXor());
        }
  }

Here we register a new built-in function called IXor. You can also register multiple built-in functions if you prefer.

The next part is creating one class each for every new built-in. Each such class has to implement the org.cytoscape.equations.Function interface usually via org.cytoscape.equations.AbstractFunction. The easiest way to get started is to peruse the existing built-ins in equations Cytoscape core library and look for a function with a similar or identical argument list. If you can't find one it may still be instructive to read through the implementation of a couple of existing functions.

First you have to create the constructor where you describe the arguments that your function will take:

public IXor() {
        super(new ArgDescriptor[] {
                        new ArgDescriptor(ArgType.INT, "arg1", "A quantity that can be converted to an integer."),
                        new ArgDescriptor(ArgType.INT, "arg2", "A quantity that can be converted to an integer."),
                });

The most trivial to implement methods are getName(), and getFunctionSummary().

/**                                                                                                                                                                                                                                                  
 *  Used to parse the function string.  This name is treated in a case-insensitive manner!                                                                                                                                                           
 *  @return the name by which you must call the function when used in an attribute equation.                                                                                                                                                        
 */
public String getName() { return "IXOR"; }

/**                                                                                                                                                                                                                                                  
  *  Used to provide help for users.                                                                                                                                                                                                                  
  *  @return a description of what this function does                                                                                                                                                                                                
  */
public String getFunctionSummary() { return "Returns an integer value that is the exclusive-or of 2 other integer values."; }

The next method is still simple but already touches on the one area that is somewhat complicated in attribute functions: data types and data type conversions!

public Class getReturnType() { return Long.class; }

Our example function is supposed to return an integer value. Integers in equation functions are represented as instances of class java.lang.Long. Therefore it is imperative not to return Integer.class! The user of the function can be blissfully unaware of this distinction. Just remember to always substitute Long for Integer and you should be fine.

The next method evaluateFunction() is the one that gets called when an expression is being evaluated. No argument type-checking is needed here because the compiler already took care of that for us. But, we need to handle all possible valid argument types and counts. (N.B., functions may be overloaded and/or variadic.) In this example the arguments can be any combination of Long and Double.

public Object evaluateFunction(final Object[] args) {
        long arg1;
        try {
                arg1 = FunctionUtil.getArgAsLong(args[0]);
        } catch (final Exception e) {
                throw new IllegalArgumentException("IXOR: can't convert the 1st argument to an integer!");
        }

        long arg2;
        try {
                arg2 = FunctionUtil.getArgAsLong(args[0]);
        } catch (final Exception e) {
                throw new IllegalArgumentException("IXOR: can't convert the 2nd argument to an integer!");
        }

        final long result = arg1 ^ arg2;
        return (Long)result;
}

How to add plug-in specific help to the Cytoscape main help system?

If you download Sample 24 and instal and copy the jar to the deploy directory fo your running Cytoscape, you will see topic Sample 24 help is added to your help panel (Help --> Contents...). In order to make it simpler, you can download the help directory in the sampel 24 trunk and copy this folder to your project's resources folder. Next you need to get the CyHelpBroker service in your CyActivator class. The code in sample 24:

import java.util.Properties;

import org.cytoscape.application.swing.CyHelpBroker;
import org.cytoscape.service.util.AbstractCyActivator;
import org.osgi.framework.BundleContext;

public class CyActivator extends AbstractCyActivator {

        @Override
        public void start(BundleContext context) throws Exception {
                
                CyHelpBroker cyHelpBroker = getService(context, CyHelpBroker.class);

                AppHelp action = new AppHelp(cyHelpBroker);
                registerAllServices(context, action, new Properties());
        }

}

In the main entry point of your plug-in, add the following function:

...
import java.net.URL;
import org.cytoscape.application.swing.CyHelpBroker;
import javax.help.HelpSet;
...
        /**
         *  Hook plugin help into the Cytoscape main help system:
         */
        private void addHelp() {
                final String HELP_SET_NAME = "/help/jhelpset";
                final ClassLoader classLoader = AppHelp.class.getClassLoader();
                URL helpSetURL;
                try {
                        helpSetURL = HelpSet.findHelpSet(classLoader, HELP_SET_NAME);
                        final HelpSet newHelpSet = new HelpSet(classLoader, helpSetURL);
                        cyHelpBroker.getHelpSet().add(newHelpSet);
                } catch (final Exception e) {
                        System.err.println("Sample24: Could not find help set: \"" + HELP_SET_NAME + "!");
                }
        }

Invoke this function somewhere in the constructor for the class. Finally, edit the files in the help directory. Most likely you would want to edit the files named jhelpmap.jhm and Topic.html. You may consider removing both, SubTopic.html and the reference to it in jhelpmap.jhm. You can also add additional topics, if you want. The effect this will have is to add a new topic at the very bottom of the Cytoscape help index. You may have a help button in your plug-in, in which case you would probably want to add code similar to the following:

       ...
import cytoscape.view.CyHelpBroker;
       ...
       CyHelpBroker.getHelpBroker().enableHelpOnButton(helpButton, "Topic", null);
       ...

That should be all that is needed to dynamically add your own help topic(s)!

How to add NetworkViewTaskFactories to the right click or double click menus on network view?

First the customized TaskFactory must implement NetworkViewTaskFactory interface or extend AbstractNetworkViewTaskFactory. Secondly, the service property "preferredAction" should be set to be "OPEN" for double click, or "NEW" for right click menu.

 MyNetworkViewTaskFactory myNetworkViewTaskFactory = new MyNetworkViewTaskFactory(applicationManagerManagerServiceRef);

 // Add double click menu to the network view
 Properties myNetworkViewTaskFactoryProps = new Properties();           
 myNetworkViewTaskFactoryProps.setProperty("preferredAction","OPEN");
 myNetworkViewTaskFactoryProps.setProperty("title","my title");

 // Register the service
 registerService(bc,myNetworkViewTaskFactory,NetworkViewTaskFactory.class, myNetworkViewTaskFactoryProps);

This also applies to add menu item to the double click / right click of nodeView or edgeView.

 // To add a right click menu item on node view, set "preferredAction" to "NEW"
 MyNodeViewTaskFactory myNodeViewTaskFactory = new MyNodeViewTaskFactory();

 // Add double click menu item to the node view
 Properties myNodeViewTaskFactoryProps = new Properties();              
 myNodeViewTaskFactoryProps.setProperty("preferredAction","NEW");
 myNodeViewTaskFactoryProps.setProperty("title","my node action");

 // Register the service
 registerService(bc,myNodeViewTaskFactory,NodeViewTaskFactory.class, myNodeViewTaskFactoryProps);

The source code of sample Apps can be find here.

How to add a context menu to edge view or node view in your app?

Sample 26 is an example of using CyNodeViewContextMenuFactory and CyEdgeViewContextMenuFactory for adding a menu item to the popup menu of node and edge views in the network view panel. these context menu factories are mainly different from using NodeViewTaskFactory in that the manu item is directly accessible and can be modified. Below, two example codes for adding a menu item to right click menu on node and edge, respectively, is shown:

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;

import javax.swing.JMenuItem;
import javax.swing.JOptionPane;

import org.cytoscape.application.swing.CyMenuItem;
import org.cytoscape.application.swing.CyNodeViewContextMenuFactory;
import org.cytoscape.model.CyNode;
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.model.View;

public class CyNodeVCMFSample implements CyNodeViewContextMenuFactory, ActionListener{

        @Override
        public CyMenuItem createMenuItem(CyNetworkView netView,
                        View<CyNode> nodeView) {
                
                JMenuItem jMenu = new JMenuItem("sample CyNodeVCMF");
                jMenu.addActionListener(this);
                CyMenuItem newMenu = new CyMenuItem(jMenu, 1);
                return newMenu;
                
        }

        public void actionPerformed(ActionEvent e) {

                // Write your own function here.
                JOptionPane.showMessageDialog(null, "CyNodeViewContextMenuFactory worked!");
                
        }
}

import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;

import javax.swing.JMenuItem;
import javax.swing.JOptionPane;

import org.cytoscape.application.swing.CyEdgeViewContextMenuFactory;
import org.cytoscape.application.swing.CyMenuItem;
import org.cytoscape.model.CyEdge;
import org.cytoscape.view.model.CyNetworkView;
import org.cytoscape.view.model.View;

public class CyEdgeVCNMFSample implements CyEdgeViewContextMenuFactory, ActionListener  {

        @Override
        public CyMenuItem createMenuItem(CyNetworkView netView,
                        View<CyEdge> edgeView) {
                JMenuItem newMenuItem = new JMenuItem("Sample cyEdgeVNMF");
                newMenuItem.addActionListener(this);
                CyMenuItem edgeMenu = new CyMenuItem(newMenuItem, 1);
                return edgeMenu;
        }

        @Override
        public void actionPerformed(ActionEvent e) {
                
                // Write your own function here.
                JOptionPane.showMessageDialog(null, "CyEdgeViewContextMenuFactory action worked!");
                
        }
        
}

As you can see, the requested menu item is defined and modified (the text is set) in these code, whereas in NetworkViewTaskFactory the menu items are generated automatically. In addition to CyNodeViewContextMenuFactory interface, ActionListener interface is also required to be implemented in order to perform the required action when menu item is selected (click).

It is also important to note that, any classes implementing these context meny factory interfaces, requires to be registered in the CyActiavtor:

import java.util.Properties;

import org.cytoscape.application.swing.CyEdgeViewContextMenuFactory;
import org.cytoscape.application.swing.CyNodeViewContextMenuFactory;
import org.cytoscape.service.util.AbstractCyActivator;
import org.osgi.framework.BundleContext;

public class CyActivator extends AbstractCyActivator {

        @Override
        public void start(BundleContext context) throws Exception {
                CyNodeViewContextMenuFactory cyNodeVCMF  = new CyNodeVCMFSample();
                CyEdgeViewContextMenuFactory cyEdgeVCMF = new CyEdgeVCNMFSample();
                
                Properties properties = new Properties();
                registerAllServices(context, cyNodeVCMF, properties);
                registerAllServices(context, cyEdgeVCMF, properties);
                
        }

}

How to build a network reader to support my own format?

First, we should define the format of my network file and its file extension. Let's say, each line in our network file has two columns, tab-delimited. And we define file extension '.tc', stands for 'two columns'.

  //1. define a file filter (BasicCyFileFilter), to support the reader to read the file with extension '.tc'
  HashSet<String> extensions = new HashSet<String>();
  extensions.add("tc");
  HashSet<String> contentTypes = new HashSet<String>();
  contentTypes.add("txt");
  String description = "My test filter";
  DataCategory category = DataCategory.NETWORK;
  BasicCyFileFilter filter = new BasicCyFileFilter(extensions,contentTypes, description, category, swingAdapter.getStreamUtil());


  //2. Create an instance of the ReaderFactory
  // Note that extends TCReaderFactory  must implement the interface InputStreamTaskFactory or extends the class  AbstractInputStreamTaskFactory.
  // And the defined task must implement CyNetworkReader
  TCReaderFactory factory = new TCReaderFactory(filter, swingAdapter.getCyNetworkFactory(), swingAdapter.getCyNetworkViewFactory());

  

  //3. register the ReaderFactory as an InputStreamTaskFactory.
  Properties props = new Properties();
  props.setProperty("readerDescription","TC file reader");
  props.setProperty("readerId","tcNetworkReader");
  swingAdapter.getCyServiceRegistrar().registerService(factory, InputStreamTaskFactory.class, props);

Compile [http://chianti.ucsd.edu/svn/core3/samples/trunk/sample27a|this sample code], and install the app in Cytoscape. When we try to import a network from a file (File-->Import-->Network-->File..), we will find file type '.tc' is listed as one of the file types supported by Cytoscape.

How to add CyProperty to save values across sessions?

CyProperty acts as a container to save properties of the type (key, value) across sessions. They are available for the user to manually change in the preference menu option.

        //1. Adding a property which saves the node border width selected by the user.
        public static String NodeBorderWidthInPaths = "NODE_BORDER_WIDTH_IN_PATHS";
        public static Double NodeBorderWidthInPathsValue = 20.0;
        public static Properties nodeBorderWidthProps = new Properties();

        //2. Find if the CyProperty already exists, if not create one with default value.
        CyProperty<Properties> nodeBorderWidthProperty = null;
        CySessionManager mySessionManager;
        mySessionManager = adapter.getCySessionManager();
        CySession session;
        session = mySessionManager.getCurrentSession();
        if(session.equals(null))
                System.out.println("session null");
                
        //3. Get all properties and loop through to find your own.
        Set<CyProperty<?>> props = new HashSet<CyProperty<?>>();
        props = session.getProperties();
        if(props.equals(null))
                System.out.println("props null");
        boolean flag = false;
        
        for (CyProperty<?> prop : props) {
            if (prop.getName() != null){
                if (prop.getName().equals(NodeBorderWidthInPaths)) {
                nodeBorderWidthProperty = (CyProperty<Properties>) prop;
                flag = true;
                break;
                }
            }
        }
        
        //4. If the property does not exists, create nodeBorderWidthProperty
        if (!flag)
        {
                nodeBorderWidthProps.setProperty(NodeBorderWidthInPaths, NodeBorderWidthInPathsValue.toString());
                nodeBorderWidthProperty = new 
                                SimpleCyProperty(NodeBorderWidthInPaths, 
                                                nodeBorderWidthProps, Float.TYPE, CyProperty.SavePolicy.SESSION_FILE_AND_CONFIG_DIR );
        }
        //5. If not null, property exists, get value from it and set NodeBorderWidthInPathsValue
        else
        {
                nodeBorderWidthProps = nodeBorderWidthProperty.getProperties();
                NodeBorderWidthInPathsValue = Double.valueOf((String)nodeBorderWidthProps.get(NodeBorderWidthInPaths));
        }

How to build a plugin with dependency on 3rd party library?

   1 
   2

Trouble shooting

If you get compile error,

Check the version number of parent POM, the latest is at Cytoscape repository
If this is a dependency problem, check the version number of depended bundle at Cytoscape repository

Recommendations

If you’re a beginner you probably want to use the Simple app type. see example02a, example03a
If you want to port as quickly as possible, again, go with the Simple app type.
If you want to publish an API you must use the Bundle app type
If you experience version conflicts or anticipate future version conflicts, again you must use the Bundle app type.
If you are in doubt, you should probably use the Simple app type. You can always port it to the Bundle app type later should that become necessary. Both styles are supported and will be until (at least) version 4.0.

App Porting Hints

How to

get current network --- see sample app 5
get attributes --- see sample app 11
add a menu item --- see sample app 3

Questions, suggestions

Please send e-mail to cytoscape help desk or discussion group

Cytoscape_3/AppDeveloper/Cytoscape_3_App_Cookbook (last edited 2020-02-05 19:54:29 by KristinaHanspers)

-  ← Revision 1 as of 2012-03-16 23:49:36 →
  Size: 367
  Editor: server2
  Comment:
+  ← Revision 72 as of 2013-01-03 23:09:19 →
  Size: 41133
  Editor: server2
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-Describe Cytoscape_3/AppDeveloper/Cytoscape_3_App_Cookbook here.



About the cookbook
+= Do you want to share your own code snippet? =



Let us know! Email <samad.lotia@gladstone.ucsf.edu> to have your snippet included in this cookbook.



<<TableOfContents(2)>>

= About the cookbook =
-Line 11:
+Line 14:
+= How to use the cookbook? =

SVN repository: {{{http://chianti.ucsd.edu/svn/core3/samples/trunk/}}}



Steps:



 1. Check out sample project from SVN repository with the above URL

 1. Compile with {{{mvn clean install}}}

 1. Copy the jar in the project target directory to Cytoscape installation: deploy directory

 1. Start Cytoscape 3.0 





= The list of app examples in the cookbook =



The list of sample apps is basically the same as in [[http://cytoscape.wodaklab.org/wiki/plugin_developer_tutorial|the cookbook for Cytoscape 2.X]]. They are mostly Cytoscape Bundle apps, but also include a few Simple apps. Some of them are,



== Introduction ==

This tutorial will show some code snippets about how to use Cytoscape APIs on app development. Each feature is included in a sample app, which can serve as a starting point or template for new app developers. The code snippets can also be used as reference for experienced developers.



Cytoscape app is usually packaged in a jar file and deployed to the deploy directory of Cytoscape. When Cytoscape starts up and initializes, its app manager will look up all the apps in deploy directory. 



There are two types of Cytoscape App, Bundle app and Simplified App. In this cook book, we provide sample for both types.



If app developer will share and publish their Apps, they are encouraged to submit their Apps to Cytoscape app store website at http://apps.cytoscape.org/ . 



== How to add a tabbed Panel to Control panel? ==

Here's how to add a tabbed panel to the control panel. 

{{{

#!java

// Define a CytoPanel class

public class MyCytoPanel extends JPanel implements CytoPanelComponent {



    ...

    @Override

    public CytoPanelName getCytoPanelName() {

 return CytoPanelName.WEST;

    }

     ...

}

}}}



{{{

#!java

// In the start method of your CyActivator class:

//   Create an instance:

MyCytoPanel myPanel = new MyPanel();

//   Register it as a service:

registerService(bc,myCytoPanel,CytoPanelComponent.class, new Properties());

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].

 

== How to add an image icon (menu item) to the toolbar? ==





{{{

#!java

// Define a CyAction class

public class AddImageIconAction extends AbstractCyAction {

 

    public AddImageIconAction(CySwingApplication desktopApp){

        ...

        ImageIcon icon = new ImageIcon(getClass().getResource("/images/tiger.jpg"));



 putValue(LARGE_ICON_KEY, icon);

       ...

    }



    public boolean isInToolBar() {

 return true;

    }

    ...

}

}}}



{{{

#!java

// In the start method of your CyActivator class:

//   Create an instance:

AddImageIconAction addImageIconAction = new AddImageIconAction(cytoscapeDesktopService);

//   Register it as a service:

registerService(bc,addImageIconAction,CyAction.class, new Properties());

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to create a submenu? ==



{{{

#!java

// Define a CyAction class

public class Sample04 extends AbstractCyAction {

    ...

    public Sample04(CySwingApplication desktopApp){

 // Add a sub-menu item -- Apps->Sample04->sample04

 super("sample04...");

 setPreferredMenu("Apps.Sample04");

 //Specify the menuGravity value to put the menuItem in the desired place

        setMenuGravity(2.0f);

        ...

    }

}}}



{{{

#!java

// In the start method of your CyActivator class:

//   Create an instance:

Sample04 Sample04Action = new Sample04(cytoscapeDesktopService);

//   Register it as a service:

registerService(bc,Sample04Action,CyAction.class, new Properties());

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].





== How to create, modify, and destroy a network, nodes, and edges? ==

To create a network, get a reference to the `CyNetworkFactory` service, and tell it to create a network. With the new network, nodes and edges can be created through the CyNetwork interface. 

{{{

#!java

  // To get a reference of CyNetworkFactory at CyActivator class of the App

  CyNetworkFactory cyNetworkFactoryServiceRef = getService(bc,CyNetworkFactory.class);



...



  // To create a new network

  CyNetwork myNet = cnf.createNetwork();



...



  // Add two nodes to the network

  CyNode node1 = myNet.addNode();

  CyNode node2 = myNet.addNode();

   

  // set name for new nodes

  myNet.getDefaultNodeTable().getRow(node1.getSUID()).set("name", "Node1");

  myNet.getDefaultNodeTable().getRow(node2.getSUID()).set("name", "Node2");

  

  // Add an edge

  myNet.addEdge(node1, node2, true);



}}}



Destroying networks is done through the `CyNetworkManager` service.



First, in the `start` method of your `CyActivator` class:

{{{

#!java

  // Get a CyNetworkManager

  CyNetworkManager netMgr = getService(bc,CyNetworkManager.class);

}}}



Now you can use `CyNetworkManager` in your code:

{{{

#!java

  // Destroy a network with NetworkManager

  netMgr.destroyNetwork(myNet);	

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== Getting node views for newly created nodes? ==



After creating a node and edge, this is how to get its view:



{{{

#!java

  CyNetworkView networkView = ...;

  CyNetwork network = networkView.getModel();

  CyEventHelper eventHelper = ...;

  CyNode newNode = network.addNode();

  network.getRow(newNode).set(CyNetwork.NAME, "New Node");

  eventHelper.flushPayloadEvents();

  View<CyNode> newNodeView = networkView.getNodeView(newNode);

}}}



After creating the node in {{{CyNetwork}}}, you have to call {{{CyEventHelper}}}'s

{{{flushPayloadEvents}}} so that the new node gets a node view. If {{{flushPayloadEvents}}}

is not called, {{{getNodeView}}} may return null.



If you are creating a bunch of nodes at once, call {{{flushPayloadEvents}}} after you have finished creating all the nodes, ''not'' after each node is created. Example:



{{{

#!java

  CyNetworkView networkView = ...;

  CyNetwork network = networkView.getModel();

  CyEventHelper eventHelper = ...;

  

  for (int i = 1; i <= 100; i++) {

    CyNode node = network.addNode();

    network.getRow(newNode).set(CyNetwork.NAME, "Node " + i);

  }

  eventHelper.flushPayloadEvents();

}}}



== How to create, modify, and destroy a network view? ==

To create a network, get a reference to the `CyNetworkViewFactory` service, and tell it to create a network view.



First, in the `start` method of your `CyActivator` class:

{{{

#!java

  // Get a CyNetworkViewFactory

  CyNetworkViewFactory cyNetworkViewFactoryServiceRef = getService(bc,CyNetworkViewFactory.class);

}}}



Now you can use `CyNetworkViewFactory` in your code:

{{{

#!java

  // Create a new network view

  CyNetworkView myView = cnvf.createNetworkView(myNet);

}}}



Destroying networks is done through the `CyNetworkViewManager` service.



First, in the `start` method of your `CyActivator` class:

{{{

#!java

  // get a CyNetworkViewManager

  CyNetworkViewManager cyNetworkViewManagerServiceRef = getService(bc,CyNetworkViewManager.class);

}}}



Now you can use `CyNetworkViewManager` in your code:

{{{

#!java

  // destroy a network view through NetworkViewManager

  networkViewManager.destroyNetworkView(myView);

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to determine which nodes are currently selected on a network? ==

We can use `CyTableUtil` to get the list of selected nodes in a network

{{{

#!java

//Get the selected nodes

  List<CyNode> nodes = CyTableUtil.getNodesInState(myNetwork,"selected",true);

}}}



== How to handle events from a network (and discuss each event type)? ==

To handle Cytoscape events, implement the listener interface and register it.

{{{

#!java

  // Define a class, which implements a listener interface

  public class MyListenerClass implements NetworkAddedListener {

    ....

    public void handleEvent(NetworkAddedEvent e){

        // do something here

    }

  }

}}}



In the `start` method of your `CyActivator` class:

{{{

#!java

  // Register the listener in the CyActivator class

  registerService(bc,myListenerClass, NetworkAddedListener.class, new Properties());

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to change the background color of a view? ==

Network background color is changed as a _visual property_.

{{{

#!java

  // Set the background of current view to RED 	

  view.setVisualProperty(BasicVisualLexicon.NETWORK_BACKGROUND_PAINT, Color.red);

  view.updateView(); 

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to zoom a network view? ==





{{{

#!java

// Get the scale and adjust

double newScale = view.getVisualProperty(NETWORK_SCALE_FACTOR).doubleValue() * scale;

view.setVisualProperty(NETWORK_SCALE_FACTOR, newScale);

...	

view.updateView();

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to load attribute data? ==



There are two step to load attribute to a table. (1) Create a global table and populate it. (2) Map the global table to specific table based on a key attribute, i.e. create virtual column for the table.

{{{

#!java

// Define a task

public class CreateTableTask extends AbstractTask {

    ....

    @Override

    public void run(TaskMonitor tm) throws IOException {

 // Step 1: create a new table

 CyTable table = tableFactory.createTable("MyAttrTable " + Integer.toString(numImports++), 

       "name", String.class, true, true);



 // create a column for the table

 String attributeNmae = "MyAttributeName"; 

 table.createColumn(attributeNmae, Integer.class, false);

  

 // Step 2: populate the table with some data

 String[] keys = {"YLL021W","YBR170C","YLR249W"}; //map to the the "name" column

 CyRow row = table.getRow(keys[0]);

 row.set(attributeNmae, new Integer(2));



 row = table.getRow(keys[1]);

 row.set(attributeNmae, new Integer(3));



 row = table.getRow(keys[2]);

 row.set(attributeNmae, new Integer(4));



 // We are loading node attribute

 Class<? extends CyTableEntry> type = CyNode.class;



 // Step 3: pass the new table to MapNetworkAttrTask

 super.insertTasksAfterCurrentTask( new MapNetworkAttrTask(type,table,netMgr,appMgr,rootNetworkManager) );

    }

    ....

}









}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].





== How to remove attributes? ==

1. get the CyTable through the network

{{{

#!java

    // case for Node table

    CyTable nodeTable = network.getDefaultNodeTable();

}}}



2. Find the column and delete it

{{{

#!java

    if(nodeTable.getColumn(columnName)!= null){

        nodeTable.deleteColumn(columnName);

    }	

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to use a web service client? ==



First define a listener of web service client and register it as service -- WebServiceHelper.  This class will keep tracker of web service clients available using a Map.



{{{

#!java



  public class WebServiceHelper {

  ...

 public void addWebServiceClient(final WebServiceClient newFactory,

   final Map properties)

 {

  webserviceMap.put(newFactory, properties);

 }



 public void removeWebServiceClient(final WebServiceClient factory,

   final Map properties)

 {

  webserviceMap.remove(factory);

 }

  ...

  }  

}}}



At running time, check if the needed service is available by looking at the map.

{{{

#!java

  Iterator<WebServiceClient> it = webserviceMap.keySet().iterator();

  

  while (it.hasNext()){

    WebServiceClient client = it.next();

    // Based on the serviceLocation, we can find if the client we are looking for is available

    System.out.println("WebService CLient client: DisplayName() is "+client.getDisplayName());

    System.out.println("WebService CLient client: ServiceLocation() is "+client.getServiceLocation());

    ....  

  }

}}}



If the needed client is found, then we can construct the query and execute the query through the API of the client.

 



== How to write a web service client? ==

Step 1. Define a UI class for the setting of the client. This UI may listen to Cytoscape events

{{{

#!java

  public class MyWebserviceClientPanel extends JPanel implements ColumnCreatedListener, ColumnDeletedListener,

    SetCurrentNetworkListener {

  ...

}

}}}





Step 2. Define a client class, which must implement WebServiceClient and pass the UI class defined at previous step to the client. If UI is not defined, the default UI will be used.

{{{

#!java

  public class MyWebserviceClient extends AbstractWebServiceGUIClient implements TableImportWebServiceClient {

  ...

  }

}}}



Step 3. After the client is registered as service, the client can be find under File-->Import->Table-->Public databases...





== How to use the VizMapper programmatically? ==



Cytosape provides services for using visual mapping programming. There services are VisualMappingManager, VisualStyleFactory and VisualMappingFunctionFactory. App should get references to these services in CyActivator class, the entry point of the app. We can create new visualStyle with VisualStyleFactory and create mapping function with VisualMappingFunctionFactory very easily. After a new visual style is created, it should register with the VisualMappingManger, in this way the new visual style will be available throughout Cytoscape.



{{{

#!java

  // To get references to services in CyActivator class

  VisualMappingManager vmmServiceRef = getService(bc,VisualMappingManager.class);

  

  VisualStyleFactory visualStyleFactoryServiceRef = getService(bc,VisualStyleFactory.class);

  

  VisualMappingFunctionFactory vmfFactoryC = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=continuous)");

  VisualMappingFunctionFactory vmfFactoryD = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=discrete)");

  VisualMappingFunctionFactory vmfFactoryP = getService(bc,VisualMappingFunctionFactory.class, "(mapping.type=passthrough)");





  // To create a new VisualStyle object and set the mapping function

  VisualStyle vs= this.visualStyleFactoryServiceRef.createVisualStyle("My visual style");





  //Use pass-through mapping

  String ctrAttrName1 = "SUID";

  PassthroughMapping pMapping = (PassthroughMapping) vmfFactoryP.createVisualMappingFunction(ctrAttrName1, String.class, attrForTest, BasicVisualLexicon.NODE_LABEL);



  vs.addVisualMappingFunction(pMapping);			





  // Add the new style to the VisualMappingManager

  vmmServiceRef.addVisualStyle(vs);





  // Apply the visual style to a NetwokView

  vs.apply(myNetworkView);

  myNetworkView.updateView();

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to apply a continuous color gradient to nodes according to their degree? ==

{{{

#!java

  

  // Set node color map to attribute "Degree"

  ContinuousMapping mapping = (ContinuousMapping)

  this.continuousMappingFactoryServiceRef.createVisualMappingFunction("Degree", Integer.class, BasicVisualLexicon.NODE_FILL_COLOR);



  // Define the points

  Double val1 = 2d;

  BoundaryRangeValues<Paint> brv1 = new BoundaryRangeValues<Paint>(Color.RED, Color.GREEN, Color.PINK);



  Double val2 = 12d;

  BoundaryRangeValues<Paint> brv2 = new BoundaryRangeValues<Paint>(Color.WHITE, Color.YELLOW, Color.BLACK);

  

  // Set the points

  mapping.addPoint(val1, brv1);

  mapping.addPoint(val2, brv2);



  // add the mapping to visual style		

  vs.addVisualMappingFunction(mapping);	



}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to load a visual properties file? ==

Cytoscape provide a service 'LoadVizmapFileTaskFactory' for loading visual styles definded in a property file.



{{{

#!java

  // get a reference to Cytoscape service -- LoadVizmapFileTaskFactory 

  LoadVizmapFileTaskFactory loadVizmapFileTaskFactory =  getService(bc,LoadVizmapFileTaskFactory.class);

}}}



{{{

#!java

  // Use the service to load visual style, 'f' is the File object to hold the visual properties 

  Set<VisualStyle> vsSet = loadVizmapFileTaskFactory.loadStyles(f);

}}}



== How to get and set node coordinate positions? ==



Given a {{{View<CyNode>}}}, here's how to get its x and y coordinate positions:

{{{

#!java

View<CyNode> nodeView = ...;

Double x = nodeView.getVisualProperty(BasicVisualLexicon.NODE_X_LOCATION);

Double y = nodeView.getVisualProperty(BasicVisualLexicon.NODE_Y_LOCATION);}}}



Here's how to set the x and y coordinate positions:

{{{

#!java

View<CyNode> nodeView = ...;

double x = ...;

double y = ...;

nodeView.setVisualProperty(BasicVisualLexicon.NODE_X_LOCATION, x);

nodeView.setVisualProperty(BasicVisualLexicon.NODE_Y_LOCATION, y);}}}



== How to write a layout algorithm? ==



First define a layout class, which implements CyLayoutAlgorithm interface or  extends AbstractLayoutAlgorithm class. Then register the layout class as a service.



{{{

#!java

  // Define a layout class

  public class MyLayout extends AbstractLayoutAlgorithm {

    ...

  }





  // Define a layout task class

  public class MyLayoutTask extends AbstractLayoutTask {

    ...



    //Perform actual layout task

    final protected void doLayout(final TaskMonitor taskMonitor) {

      ...   

    }

    ...

  }





  // Register the layout class as a service in CyActivator class

  Properties myLayoutProps = new Properties();

  myLayoutProps.setProperty("preferredMenu","My Layouts");

  registerService(bc,myLayout,CyLayoutAlgorithm.class, myLayoutProps);



}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to write a Group Viewer? ==

{{{

#!java



}}}





== How to add components to the node view, edge view, and attribute browser context menus? ==

To add a context menu to a NodeView, define a class, which extends AbstractNodeViewTaskFactory, and register the NodeViewTaskFactory as service. We can add the title of menu item by setting the service property when we register the nodeViewTaskFactory.



To add context menu to the table browser, define a class, which extends AbstractTableCellTaskFactory. Create an instance and register it as service (Note register as TableCellTaskFactory).

 

{{{

#!java

  // Define a class MyNodeViewTaskFactory 

  public class MyNodeViewTaskFactory extends AbstractNodeViewTaskFactory {

    ...

  }





  // Register myNodeViewTaskFactory as a service in CyActivator

  Properties myNodeViewTaskFactoryProps = new Properties();

  myNodeViewTaskFactoryProps.setProperty("title","My context menu title");

  registerService(bc,myNodeViewTaskFactory,NodeViewTaskFactory.class, myNodeViewTaskFactoryProps);



}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to save/restore app states? ==

There are two events, which are important for saving/restoring App state. The two evetns are SessionAboutToBeSavedEvent and SessionLoadedEvent. App should implement the two  listeners and register them.



{{{

#!java



  // Implements the session event listeners

  public class MyClass implements SessionAboutToBeSavedListener, SessionLoadedListener {



      // Save app state in a file

      public void handleEvent(SessionAboutToBeSavedEvent e){

          // save app state file "myAppStateFile"

          ...

      }



      // restore app state from a file

      public void handleEvent(SessionLoadedEvent e){



        if (e.getLoadedSession().getAppFileListMap() == null || e.getLoadedSession().getAppFileListMap().size() ==0){

            return;

        }	

 List<File> files = e.getLoadedSession().getAppFileListMap().get("myAppStateFile");

        ...

       }

  }

 



  // Register the two listeners in the CyActivator class

  registerService(bc,myClass,SessionAboutToBeSavedListener.class, new Properties());

  registerService(bc,myClass,SessionLoadedListener.class, new Properties());



}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to use the Cytoscape task monitor to show the progress of my job? ==



Get a Cytoscape service DialogTaskManager and execute the task through the taskManager.



{{{

#!java

  // Get a Cytoscape service 'DialogTaskManager' in CyActivator class

  DialogTaskManager dialogTaskManager = getService(bc, DialogTaskManager.class);





  // Define a task and set the progress in the run() method

  public class MyTask extends AbstractTask {

    ...

    public void run(final TaskMonitor taskMonitor) {

        // Give the task a title.

 taskMonitor.setTitle("My task");

        ...

 taskMonitor.setProgress(0.1);



        // do something here



        ...

 taskMonitor.setProgress(1.0);

  }





  // Execute the task through the TaskManager

  DialogTaskManager.execute(myTaskFactory);



}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].





== How to add new attribute functions via a Cytoscape App? ==

Here we will go through all the steps necessary to create a new built-in function IXOR(). The complete example code and can be downloaded from here.

The easiest part is writing the actual plug-in class, which look similar to this: 

{{{

#!java

  import org.cytoscape.equations.EquationCompiler;

  import org.cytoscape.equations.Interpreter;

  import org.cytoscape.equations.EquationParser;



  public class Sample23 {



 public Sample23(EquationCompiler eqCompilerRef, Interpreter interpreterRef){

  final EquationParser theParser = eqCompilerRef.getParser();

  theParser.registerFunction(new IXor());

 }

  }

}}}



Here we register a new built-in function called IXor. You can also register multiple built-in functions if you prefer.



The next part is creating one class each for every new built-in. Each such class has to implement the org.cytoscape.equations.Function interface usually via org.cytoscape.equations.AbstractFunction. The easiest way to get started is to peruse the existing built-ins in equations Cytoscape core library and look for a function with a similar or identical argument list. If you can't find one it may still be instructive to read through the implementation of a couple of existing functions.



First you have to create the constructor where you describe the arguments that your function will take: 



{{{

#!java

public IXor() {

        super(new ArgDescriptor[] {

                        new ArgDescriptor(ArgType.INT, "arg1", "A quantity that can be converted to an integer."),

                        new ArgDescriptor(ArgType.INT, "arg2", "A quantity that can be converted to an integer."),

                });

}}}





The most trivial to implement methods are getName(), and getFunctionSummary(). 

{{{

#!java

/**                                                                                                                                                                                                                                                  

 *  Used to parse the function string.  This name is treated in a case-insensitive manner!                                                                                                                                                           

 *  @return the name by which you must call the function when used in an attribute equation.                                                                                                                                                        

 */

public String getName() { return "IXOR"; }



/**                                                                                                                                                                                                                                                  

  *  Used to provide help for users.                                                                                                                                                                                                                  

  *  @return a description of what this function does                                                                                                                                                                                                

  */

public String getFunctionSummary() { return "Returns an integer value that is the exclusive-or of 2 other integer values."; }

}}}



The next method is still simple but already touches on the one area that is somewhat complicated in attribute functions: data types and data type conversions! 



{{{

#!java

public Class getReturnType() { return Long.class; }

}}}



Our example function is supposed to return an integer value. Integers in equation functions are represented as instances of class java.lang.Long. Therefore it is imperative not to return Integer.class! The user of the function can be blissfully unaware of this distinction. Just remember to always substitute Long for Integer and you should be fine.



The next method evaluateFunction() is the one that gets called when an expression is being evaluated. No argument type-checking is needed here because the compiler already took care of that for us. But, we need to handle all possible valid argument types and counts. (N.B., functions may be overloaded and/or variadic.) In this example the arguments can be any combination of Long and Double. 



{{{

#!java

public Object evaluateFunction(final Object[] args) {

        long arg1;

        try {

                arg1 = FunctionUtil.getArgAsLong(args[0]);

        } catch (final Exception e) {

                throw new IllegalArgumentException("IXOR: can't convert the 1st argument to an integer!");

        }



        long arg2;

        try {

                arg2 = FunctionUtil.getArgAsLong(args[0]);

        } catch (final Exception e) {

                throw new IllegalArgumentException("IXOR: can't convert the 2nd argument to an integer!");

        }



        final long result = arg1 ^ arg2;

        return (Long)result;

}

}}}



See Also



[[http://wiki.cytoscape.org/Implementing_Attribute_Equations_Functions|This tutorial]] on how to write attribute functions may also be helpful. 



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to add plug-in specific help to the Cytoscape main help system? ==



If you download Sample 24 and instal and copy the jar to the deploy directory fo your running Cytoscape, you will see topic '''Sample 24 help''' is added to your help panel (Help --> Contents...).

In order to make it simpler, you can download the [[http://chianti.ucsd.edu/svn/core3/samples/trunk/sample24/src/main/resources/help/|help]]  directory in the sampel 24 trunk and copy this folder to your project's resources folder. Next you need to get the {{{CyHelpBroker}}} service in your CyActivator class.

The code in sample 24:



{{{

#!java

import java.util.Properties;



import org.cytoscape.application.swing.CyHelpBroker;

import org.cytoscape.service.util.AbstractCyActivator;

import org.osgi.framework.BundleContext;



public class CyActivator extends AbstractCyActivator {



 @Override

 public void start(BundleContext context) throws Exception {

  

  CyHelpBroker cyHelpBroker = getService(context, CyHelpBroker.class);



  AppHelp action = new AppHelp(cyHelpBroker);

  registerAllServices(context, action, new Properties());

 }



}



}}}





In the main entry point of your plug-in, add the following function:



{{{

#!java

...

import java.net.URL;

import org.cytoscape.application.swing.CyHelpBroker;

import javax.help.HelpSet;

...

        /**

  *  Hook plugin help into the Cytoscape main help system:

  */

 private void addHelp() {

  final String HELP_SET_NAME = "/help/jhelpset";

  final ClassLoader classLoader = AppHelp.class.getClassLoader();

  URL helpSetURL;

  try {

   helpSetURL = HelpSet.findHelpSet(classLoader, HELP_SET_NAME);

   final HelpSet newHelpSet = new HelpSet(classLoader, helpSetURL);

   cyHelpBroker.getHelpSet().add(newHelpSet);

  } catch (final Exception e) {

   System.err.println("Sample24: Could not find help set: \"" + HELP_SET_NAME + "!");

  }

 }

}}}



Invoke this function somewhere in the constructor for the class.  Finally, edit the files in the help directory. Most likely you would want to edit the files named {{{jhelpmap.jhm}}} and {{{Topic.html}}}. You may consider removing both, {{{SubTopic.html}}} and the reference to it in {{{jhelpmap.jhm}}}. You can also add additional topics, if you want. The effect this will have is to add a new topic at the very bottom of the Cytoscape help index. You may have a help button in your plug-in, in which case you would probably want to add code similar to the following:



{{{

#!java

       ...

import cytoscape.view.CyHelpBroker;

       ...

       CyHelpBroker.getHelpBroker().enableHelpOnButton(helpButton, "Topic", null);

       ...

}}}



That should be all that is needed to dynamically add your own help topic(s)!



== How to add NetworkViewTaskFactories to the right click or double click menus on network view? ==



First the customized TaskFactory must implement NetworkViewTaskFactory interface or extend AbstractNetworkViewTaskFactory. Secondly, the service property "preferredAction" should be set to be "OPEN" for double click, or "NEW" for right click menu.



{{{

#!java



 MyNetworkViewTaskFactory myNetworkViewTaskFactory = new MyNetworkViewTaskFactory(applicationManagerManagerServiceRef);



 // Add double click menu to the network view

 Properties myNetworkViewTaskFactoryProps = new Properties();		

 myNetworkViewTaskFactoryProps.setProperty("preferredAction","OPEN");

 myNetworkViewTaskFactoryProps.setProperty("title","my title");



 // Register the service

 registerService(bc,myNetworkViewTaskFactory,NetworkViewTaskFactory.class, myNetworkViewTaskFactoryProps);

}}}



This also applies to add menu item to the double click / right click of nodeView or edgeView.



{{{

#!java

 // To add a right click menu item on node view, set "preferredAction" to "NEW"

 MyNodeViewTaskFactory myNodeViewTaskFactory = new MyNodeViewTaskFactory();



 // Add double click menu item to the node view

 Properties myNodeViewTaskFactoryProps = new Properties();		

 myNodeViewTaskFactoryProps.setProperty("preferredAction","NEW");

 myNodeViewTaskFactoryProps.setProperty("title","my node action");



 // Register the service

 registerService(bc,myNodeViewTaskFactory,NodeViewTaskFactory.class, myNodeViewTaskFactoryProps);

}}}



The source code of sample Apps can be find [[http://chianti.ucsd.edu/svn/core3/samples/trunk/|here]].



== How to add a context menu to edge view or node view in your app? ==



[[http://chianti.ucsd.edu/svn/core3/samples/trunk/sample26/|Sample 26]] is an example of using {{{CyNodeViewContextMenuFactory}}} and {{{CyEdgeViewContextMenuFactory}}} for adding a menu item to the popup menu of node and edge views in the network view panel. these context menu factories are mainly different from using {{{NodeViewTaskFactory}}} in that the manu item is directly accessible and can be modified. Below, two example codes for adding a menu item to right click menu on node and edge, respectively, is shown: 



{{{

#!java

import java.awt.event.ActionEvent;

import java.awt.event.ActionListener;



import javax.swing.JMenuItem;

import javax.swing.JOptionPane;



import org.cytoscape.application.swing.CyMenuItem;

import org.cytoscape.application.swing.CyNodeViewContextMenuFactory;

import org.cytoscape.model.CyNode;

import org.cytoscape.view.model.CyNetworkView;

import org.cytoscape.view.model.View;



public class CyNodeVCMFSample implements CyNodeViewContextMenuFactory, ActionListener{



 @Override

 public CyMenuItem createMenuItem(CyNetworkView netView,

   View<CyNode> nodeView) {

  

  JMenuItem jMenu = new JMenuItem("sample CyNodeVCMF");

  jMenu.addActionListener(this);

  CyMenuItem newMenu = new CyMenuItem(jMenu, 1);

  return newMenu;

  

 }



 public void actionPerformed(ActionEvent e) {



  // Write your own function here.

  JOptionPane.showMessageDialog(null, "CyNodeViewContextMenuFactory worked!");

  

 }

}

}}}





{{{

#!java

import java.awt.event.ActionEvent;

import java.awt.event.ActionListener;



import javax.swing.JMenuItem;

import javax.swing.JOptionPane;



import org.cytoscape.application.swing.CyEdgeViewContextMenuFactory;

import org.cytoscape.application.swing.CyMenuItem;

import org.cytoscape.model.CyEdge;

import org.cytoscape.view.model.CyNetworkView;

import org.cytoscape.view.model.View;



public class CyEdgeVCNMFSample implements CyEdgeViewContextMenuFactory, ActionListener  {



 @Override

 public CyMenuItem createMenuItem(CyNetworkView netView,

   View<CyEdge> edgeView) {

  JMenuItem newMenuItem = new JMenuItem("Sample cyEdgeVNMF");

  newMenuItem.addActionListener(this);

  CyMenuItem edgeMenu = new CyMenuItem(newMenuItem, 1);

  return edgeMenu;

 }



 @Override

 public void actionPerformed(ActionEvent e) {

  

  // Write your own function here.

  JOptionPane.showMessageDialog(null, "CyEdgeViewContextMenuFactory action worked!");

  

 }

 

}

}}}



As you can see, the requested menu item is defined and modified (the text is set) in these code, whereas in [[http://wiki.cytoscape.org/Cytoscape_3/AppDeveloper/Cytoscape_3_App_Cookbook#How_to_add_NetworkViewTaskFactories_to_the_right_click_or_double_click_menus_on_network_view.3F|NetworkViewTaskFactory]] the menu items are generated automatically. In addition to {{{CyNodeViewContextMenuFactory}}} interface, {{{ActionListener}}} interface is also required to be implemented in order to perform the required action when menu item is selected (click). 



It is also important to note that, any classes implementing these context meny factory interfaces, requires to be registered in the CyActiavtor:



{{{

#!java

import java.util.Properties;



import org.cytoscape.application.swing.CyEdgeViewContextMenuFactory;

import org.cytoscape.application.swing.CyNodeViewContextMenuFactory;

import org.cytoscape.service.util.AbstractCyActivator;

import org.osgi.framework.BundleContext;



public class CyActivator extends AbstractCyActivator {



 @Override

 public void start(BundleContext context) throws Exception {

  CyNodeViewContextMenuFactory cyNodeVCMF  = new CyNodeVCMFSample();

  CyEdgeViewContextMenuFactory cyEdgeVCMF = new CyEdgeVCNMFSample();

  

  Properties properties = new Properties();

  registerAllServices(context, cyNodeVCMF, properties);

  registerAllServices(context, cyEdgeVCMF, properties);

  

 }



}



}}}



== How to build a network reader to support my own format? ==



First, we should define the format of my network file and its file extension. Let's say, each line in our network file has two columns, tab-delimited. And we define file extension '.tc', stands for 'two columns'.



{{{

#!java

  //1. define a file filter (BasicCyFileFilter), to support the reader to read the file with extension '.tc'

  HashSet<String> extensions = new HashSet<String>();

  extensions.add("tc");

  HashSet<String> contentTypes = new HashSet<String>();

  contentTypes.add("txt");

  String description = "My test filter";

  DataCategory category = DataCategory.NETWORK;

  BasicCyFileFilter filter = new BasicCyFileFilter(extensions,contentTypes, description, category, swingAdapter.getStreamUtil());





  //2. Create an instance of the ReaderFactory

  // Note that extends TCReaderFactory  must implement the interface InputStreamTaskFactory or extends the class  AbstractInputStreamTaskFactory.

  // And the defined task must implement CyNetworkReader

  TCReaderFactory factory = new TCReaderFactory(filter, swingAdapter.getCyNetworkFactory(), swingAdapter.getCyNetworkViewFactory());



  



  //3. register the ReaderFactory as an InputStreamTaskFactory.

  Properties props = new Properties();

  props.setProperty("readerDescription","TC file reader");

  props.setProperty("readerId","tcNetworkReader");

  swingAdapter.getCyServiceRegistrar().registerService(factory, InputStreamTaskFactory.class, props);

}}}



Compile [http://chianti.ucsd.edu/svn/core3/samples/trunk/sample27a|this sample code], and install the app in Cytoscape. When we try to import a network from a file (File-->Import-->Network-->File..), we will find file type '.tc' is listed as one of the file types supported by Cytoscape.



== How to add CyProperty to save values across sessions? ==



CyProperty acts as a container to save properties of the type (key, value) across sessions. They are available for the user to manually change in the preference menu option.



{{{

#!java

 //1. Adding a property which saves the node border width selected by the user.

 public static String NodeBorderWidthInPaths = "NODE_BORDER_WIDTH_IN_PATHS";

 public static Double NodeBorderWidthInPathsValue = 20.0;

 public static Properties nodeBorderWidthProps = new Properties();



 //2. Find if the CyProperty already exists, if not create one with default value.

 CyProperty<Properties> nodeBorderWidthProperty = null;

 CySessionManager mySessionManager;

 mySessionManager = adapter.getCySessionManager();

 CySession session;

 session = mySessionManager.getCurrentSession();

 if(session.equals(null))

  System.out.println("session null");

  

 //3. Get all properties and loop through to find your own.

 Set<CyProperty<?>> props = new HashSet<CyProperty<?>>();

 props = session.getProperties();

 if(props.equals(null))

  System.out.println("props null");

 boolean flag = false;

 

 for (CyProperty<?> prop : props) {

     if (prop.getName() != null){

      if (prop.getName().equals(NodeBorderWidthInPaths)) {

         nodeBorderWidthProperty = (CyProperty<Properties>) prop;

         flag = true;

         break;

      }

     }

 }

 

 //4. If the property does not exists, create nodeBorderWidthProperty

 if (!flag)

 {

  nodeBorderWidthProps.setProperty(NodeBorderWidthInPaths, NodeBorderWidthInPathsValue.toString());

  nodeBorderWidthProperty = new 

    SimpleCyProperty(NodeBorderWidthInPaths, 

      nodeBorderWidthProps, Float.TYPE, CyProperty.SavePolicy.SESSION_FILE_AND_CONFIG_DIR );

 }

 //5. If not null, property exists, get value from it and set NodeBorderWidthInPathsValue

 else

 {

  nodeBorderWidthProps = nodeBorderWidthProperty.getProperties();

  NodeBorderWidthInPathsValue = Double.valueOf((String)nodeBorderWidthProps.get(NodeBorderWidthInPaths));

 }

}}}







== How to build a plugin with dependency on 3rd party library? ==

{{{

#!java



}}}







= Trouble shooting =



If you get compile error,



 1. Check the version number of parent POM, the latest is at [[http://chianti.ucsd.edu/svn/core3/parent/trunk|Cytoscape repository]]

 1. If this is a dependency problem, check the version number of depended bundle at  [[http://cytoscape.wodaklab.org/nexus/index.html|Cytoscape repository]]





= Recommendations =

 1. If you’re a beginner you probably want to use the Simple app type. see example02a, example03a

 1. If you want to port as quickly as possible, again, go with the Simple app type.

 1. If you want to publish an API you must use the Bundle app type

 1. If you experience version conflicts or anticipate future version conflicts, again you must use the Bundle app type.

 1. If you are in doubt, you should probably use the Simple app type. You can always port it to the Bundle app type later should that become necessary. Both styles are supported and will be until (at least) version 4.0. 





= App Porting Hints =

How to



 1. get current network --- see sample app 5

 1. get attributes --- see sample app 11

 1. add a menu item --- see sample app 3 



= Questions, suggestions =



Please send e-mail to [[http://groups.google.com/group/cytoscape-helpdesk?pli=1|cytoscape help desk]] or [[http://groups.google.com/group/cytoscape-discuss|discussion group]]

Diff for "Cytoscape_3/AppDeveloper/Cytoscape_3_App_Cookbook"

Do you want to share your own code snippet?

About the cookbook

How to use the cookbook?

The list of app examples in the cookbook

Introduction

How to add a tabbed Panel to Control panel?

How to add an image icon (menu item) to the toolbar?

How to create a submenu?

How to create, modify, and destroy a network, nodes, and edges?

Getting node views for newly created nodes?

How to create, modify, and destroy a network view?

How to determine which nodes are currently selected on a network?

How to handle events from a network (and discuss each event type)?

How to change the background color of a view?

How to zoom a network view?

How to load attribute data?

How to remove attributes?

How to use a web service client?

How to write a web service client?

How to use the VizMapper programmatically?

How to apply a continuous color gradient to nodes according to their degree?

How to load a visual properties file?

How to get and set node coordinate positions?

How to write a layout algorithm?

How to write a Group Viewer?

How to add components to the node view, edge view, and attribute browser context menus?

How to save/restore app states?

How to use the Cytoscape task monitor to show the progress of my job?

How to add new attribute functions via a Cytoscape App?

How to add plug-in specific help to the Cytoscape main help system?

How to add NetworkViewTaskFactories to the right click or double click menus on network view?

How to add a context menu to edge view or node view in your app?

How to build a network reader to support my own format?

How to add CyProperty to save values across sessions?

How to build a plugin with dependency on 3rd party library?

Trouble shooting

Recommendations

App Porting Hints

Questions, suggestions