Diff for "CytoPanel_Tutorial"

About this Page

This page describes what CytoPanels are, how to use them, and how to programmatically access them. This feature is new in 2.2

What are CytoPanels?

CytoPanels are floatable / dockable panels, which will be available in Cytoscape 2.2. We built the CytoPanel API to cut down on the number of pop-up windows within Cytoscape, and create a more unified user experience. For example, in Cytoscape 2.1, the cPath Plugin enables users to click on a node and immediately view node details in a pop-up window. Using the CytoPanel API, we can now show these node details in an embedded CytoPanel, and present a more integrated experience to the user. For example, the image below shows a screenshot of the latest BioPAX Plugin. When you click on a node, the node details appear directly in the left CytoPanel.

http://cbio.mskcc.org/~cerami/biopax/bp_plugin1.png

The user can then chose to resize, hide or float the left CytoPanel. For example, in the screenshot below, the user has chosen to float it:

http://cbio.mskcc.org/~cerami/biopax/bp_plugin2.png

Basic Usage

Cytoscape 2.2 now includes three CytoPanels: CytoPanel 1 (appears on the left), CytoPanel 2 (appears on the bottom), and CytoPanel 3 (appears on the right). By default, only CytoPanel 1 will appear, and it will automatically contain the network list and bird's eye view component. The other panels will be hidden.

The end-user can show / hide any panel via the new CytoPanel menu, or via the keyboard accelerator short-cuts.

Working with the CytoPanel API

The CytoPanel API is straightforward and fully documented. If you are a core Cytoscape coder or a Plugin writer, here are a few tips to get started.

Step 1: Obtain a CytoPanel

As noted above, the Cytoscape Desktop contains three default CytoPanels. To obtain one, use the CytoscapeDesktop.getCytoPanel() method. This method takes a SwingConstants integer value, indicating a compass direction (this enables us to add additional CytoPanels in the future, if we decide that's necessary.) Here is sample code for accessing the left CytoPanel:

   1    CytoscapeDesktop desktop = Cytoscape.getDesktop();
   2    CytoPanel cytoPanel = desktop.getCytoPanel (SwingConstants.WEST);
   3 

Step 2: Add your component

You can place any Swing Component (typically a JPanel) object in a CytoPanel, and it will automatically get its own tab. For example, in the code below, I create a BioPAX component, and add it the left CytoPanel. The code also adds an icon and a tooltip:

   1    BioPaxContainer bpContainer = BioPaxContainer.getInstance();
   2    CytoscapeDesktop desktop = Cytoscape.getDesktop();
   3    CytoPanel cytoPanel = desktop.getCytoPanel (SwingConstants.WEST);
   4    URL url = BioPaxDetailsPanel.class.getResource("resources/read_obj.gif");
   5    Icon icon = new ImageIcon(url);
   6    cytoPanel.add("BioPax PlugIn", icon, bpContainer, "BioPax PlugIn");
   7 

Step 3: Set the CytoPanel State

You can also (optionally) set the CytoPanel state. Each CytoPanel exists in one of three states:

• CytoPanelState.HIDE: The panel is hidden from the user's view.

• CytoPanelState.FLOAT: The panel is floating in a separate, external window frame.

• CytoPanelState.DOCK: The panel is docked in the main Cytoscape window, and visible to the user.

Here is sample code for setting the current state:

   1    cytoPanel.setState(CytoPanelState.DOCK);
   2 

If you want, you can also activate your tab within a CytoPanel. To do so, first determine the index value of your component. Then, call setSelectedIndex(). For example:

   1    int index = cytoPanel.indexOfComponent(myComponent);
   2    cytoPanel.setSelectedIndex(index);
   3 

CytoPanel Events

You can also (optionally) register to receive CytoPanel Events. This is done via:

   1    addCytoPanelListener(CytoPanelListener);
   2    removeCytoPanelListener(CytoPanelListener);
   3 

Once you are registered to receive CytoPanel events, you will be notified of the following:

• onStateChange()

• onComponentSelected()

• onComponentAdded()

• onComponentRemoved()

See the CytoPanel Listener class docs for more information.