## These are wiki comments - leave them in so that people can see them when editing the page
  
## This template may be useful for documenting use cases 
## Developed in response to a hackathon request for formalized, detailed use cases 
##  to help direct implementation proposals

|| '''Use Case Name''' : Quick Find + Group Nodes integration ||
|| '''For Feature''' : GroupAPI ||
|| '''Editors''': JimVlasblom ||

## EXAMPLE: 
## Use Case Name: Representation of Protein Complex
## For Feature: Grouping Function
## Editors: Mr. Knowitall

<<TableOfContents([2])>>

== Summary ==
## Provide a one paragraph description of the use case
Quick find and/or Group nodes should be modified to allow the quick finder to locate nodes that have been grouped into a group node.  Group nodes need to expose its members to the quick finder, and quick find should use this to search all subnodes of a group node in addition to the group node.  Any highlighting or exploding of the group node should be handled by the group node code.  This could be used for our plugin "GenePro", which creates composite pie nodes by grouping together several genes with a common attribute that belong to the same cluster.  This creates a three level hierarchy:  clusters -> attributes -> genes.  Clusters are shown as pie nodes, and attributes as "wedges" within the pie.  Genes are hidden within these pie nodes, but there are options to "zoom in" and expand each cluster into its component genes.    Currently, GenePro has its own searching tools.  If Quick Find and Group Nodes can be modified to allow genes to be found - even if hidden in a group node (pie node) - than we could take advantage of both the Quick Find plugin and group node functionality.

In preliminary discussions with Scott and Ethan, it was decided that Quick Find should also make the item found available to the group node and other plugins, so that those plugins can properly decorate/highlight the node.  (In GenePro, for example, we would like to highlight the appropriate wedge of the pie if the item being searched is a gene attribute).  

Finally, if the Quick Find text field was available as a Swing component, it would be possible to make custom search dialogs.  This would be useful in our case, as we could create different buttons for finding genes, wedges, and clusters.  This might be considered redundant - since the user could just specify different attributes to search on.  I am concerned about usability, however, if the # of attributes is large.  It may not be an issue for us: we don't store that many attributes per node, but it may be a problem for other plugins. 

== Step-by-Step User Action ==
## Provide a step-by-step account of how the user would execute the use case.  For example: (1) right click on node, (2) choose "expand" from context menu, (3) new view is created, etc...
When executing a search with Quick Find, the entire hierarchy of grouped nodes should be searched.

## == Visual Aides ==
## Provide attachments to images to illustrate the use case (screenshots, mock-ups, storyboards, etc)

== Requirements for Cytoscape ==
## List the components/functions already in Cytoscape that are relevant to the use case and possible implementations (e.g., "current context menus can be used accomplish step 2 above")
## Also list components/functions that are needed in Cytoscape to execute the use case (e.g., "cytoscape needs to allow for multiple views of the same network for this to work")
Only visible nodes are searched currently.

== Importance ==
## Describe whether this use case is critical and how frequently users would come across it.  Describe common work flows that might involve the use case (e.g., "this use case comes up regularly, on a weekly basis, whenever we want to analyze our protein superfamily networks").
As we have another solution in place, it is not of immediate importance.  In the future, I believe that it would save us (and other developers) time if we could use an existing search solution.  The quick find plugin also contains a number of nice features (auto complete, etc.) that would be time consuming for us to add and maintain.

## == Other Examples ==
## List other applications or relevant examples outside of Cytoscape that provide some or all of the desired functionality (e.g., "You can do this using the group function in PowerPoint").

== Comments ==