==== 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 ('Control' appears on the left), CytoPanel 2 ('Data' appears on the bottom), and CytoPanel 3 ('Results' appears on the right).  By default, only the Control CytoPanel  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:

{{{
#!java
   CytoscapeDesktop desktop = Cytoscape.getDesktop();
   CytoPanel cytoPanel = desktop.getCytoPanel (SwingConstants.WEST);
}}}
=== 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:

{{{
#!java
   BioPaxContainer bpContainer = BioPaxContainer.getInstance();
   CytoscapeDesktop desktop = Cytoscape.getDesktop();
   CytoPanel cytoPanel = desktop.getCytoPanel (SwingConstants.WEST);
   URL url = BioPaxDetailsPanel.class.getResource("resources/read_obj.gif");
   Icon icon = new ImageIcon(url);
   cytoPanel.add("BioPax PlugIn", icon, bpContainer, "BioPax PlugIn");
}}}
=== 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:

{{{
#!java
   cytoPanel.setState(CytoPanelState.DOCK);
}}}
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:

{{{
#!java
   int index = cytoPanel.indexOfComponent(myComponent);
   cytoPanel.setSelectedIndex(index);
}}}
=== CytoPanel Events ===
You can also (optionally) register to receive CytoPanel Events.  This is done via:

{{{
#!java
   addCytoPanelListener(CytoPanelListener);
   removeCytoPanelListener(CytoPanelListener);
}}}
Once you are registered to receive CytoPanel events, you will be notified of the following:

 * {{{onStateChange()}}}
 * {{{onComponentSelected()}}}
 * {{{onComponentAdded()}}}
 * {{{onComponentRemoved()}}}
See [[CyAPI]] for the CytoPanel Listener class docs for more information.