src/jalview/api/FeatureRenderer.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.api;
  22
  23 import jalview.datamodel.SequenceFeature;
  24 import jalview.datamodel.SequenceI;
  25 import jalview.util.matcher.KeyedMatcherSetI;
  26
  27 import java.awt.Color;
  28 import java.awt.Graphics;
  29 import java.util.List;
  30 import java.util.Map;
  31
  32 /**
  33  * Abstract feature renderer interface
  34  *
  35  * @author JimP
  36  *
  37  */
  38 public interface FeatureRenderer
  39 {
  40
  41   /**
  42    * Computes the feature colour for a given sequence and column position,
  43    * taking into account sequence feature locations, feature colour schemes,
  44    * render ordering, feature and feature group visibility, and transparency.
  45    * <p>
  46    * The graphics argument should be provided if transparency is applied
  47    * (getTransparency() < 1). With feature transparency, visible features are
  48    * written to the graphics context and the composite colour may be read off
  49    * from it. In this case, the returned feature colour is not the composite
  50    * colour but that of the last feature drawn.
  51    * <p>
  52    * If no transparency applies, then the graphics argument may be null, and the
  53    * returned colour is the one that would be drawn for the feature.
  54    * <p>
  55    * Returns null if there is no visible feature at the position.
  56    * <p>
  57    * This is provided to support rendering of feature colours other than on the
  58    * sequence alignment, including by structure viewers and the overview window.
  59    * Note this method takes no account of whether the sequence or column is
  60    * hidden.
  61    *
  62    * @param sequence
  63    * @param column
  64    *          aligned column position (1..)
  65    * @param g
  66    * @return
  67    */
  68   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
  69
  70   /**
  71    * trigger the feature discovery process for a newly created feature renderer.
  72    */
  73   void featuresAdded();
  74
  75   /**
  76    *
  77    * @param ft
  78    * @return display style for a feature
  79    */
  80   FeatureColourI getFeatureStyle(String ft);
  81
  82   /**
  83    * update the feature style for a particular feature
  84    *
  85    * @param ft
  86    * @param ggc
  87    */
  88   void setColour(String ft, FeatureColourI ggc);
  89
  90   AlignViewportI getViewport();
  91
  92   /**
  93    *
  94    * @return container managing list of feature types and their visibility
  95    */
  96   FeaturesDisplayedI getFeaturesDisplayed();
  97
  98   /**
  99    * get display style for all features types - visible or invisible
 100    *
 101    * @return
 102    */
 103   Map<String, FeatureColourI> getFeatureColours();
 104
 105   /**
 106    * query the alignment view to find all features
 107    *
 108    * @param newMadeVisible
 109    *          - when true, automatically make newly discovered types visible
 110    */
 111   void findAllFeatures(boolean newMadeVisible);
 112
 113   /**
 114    * get display style for all features types currently visible
 115    *
 116    * @return
 117    */
 118   Map<String, FeatureColourI> getDisplayedFeatureCols();
 119
 120   /**
 121    * get all registered groups
 122    *
 123    * @return
 124    */
 125   List<String> getFeatureGroups();
 126
 127   /**
 128    * get groups that are visible/invisible
 129    *
 130    * @param visible
 131    * @return
 132    */
 133   List<String> getGroups(boolean visible);
 134
 135   /**
 136    * change visibility for a range of groups
 137    *
 138    * @param toset
 139    * @param visible
 140    */
 141   void setGroupVisibility(List<String> toset, boolean visible);
 142
 143   /**
 144    * change visibiilty of given group
 145    *
 146    * @param group
 147    * @param visible
 148    */
 149   void setGroupVisibility(String group, boolean visible);
 150
 151   /**
 152    * Returns features at the specified aligned column on the given sequence.
 153    * Non-positional features are not included. If the column has a gap, then
 154    * enclosing features are included (but not contact features).
 155    *
 156    * @param sequence
 157    * @param column
 158    *          aligned column position (1..)
 159    * @return
 160    */
 161   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence, int column);
 162
 163   /**
 164    * Returns features at the specified residue position on the given sequence.
 165    * Non-positional features are not included.
 166    *
 167    * @param sequence
 168    * @param resNo
 169    *          residue position (start..)
 170    * @return
 171    */
 172   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence, int resNo);
 173
 174   /**
 175    * get current displayed types, in ordering of rendering (on top last)
 176    *
 177    * @return a (possibly empty) list of feature types
 178    */
 179
 180   List<String> getDisplayedFeatureTypes();
 181
 182   /**
 183    * Returns a (possibly empty) list of currently visible feature groups
 184    *
 185    * @return
 186    */
 187   List<String> getDisplayedFeatureGroups();
 188
 189   /**
 190    * display all features of these types
 191    *
 192    * @param featureTypes
 193    */
 194   void setAllVisible(List<String> featureTypes);
 195
 196   /**
 197    * display featureType
 198    *
 199    * @param featureType
 200    */
 201   void setVisible(String featureType);
 202
 203   /**
 204    * Sets the transparency value, between 0 (full transparency) and 1 (no
 205    * transparency)
 206    *
 207    * @param value
 208    */
 209   void setTransparency(float value);
 210
 211   /**
 212    * Returns the transparency value, between 0 (full transparency) and 1 (no
 213    * transparency)
 214    *
 215    * @return
 216    */
 217   float getTransparency();
 218
 219   /**
 220    * Answers the filters applied to the given feature type, or null if none is
 221    * set
 222    *
 223    * @param featureType
 224    * @return
 225    */
 226   KeyedMatcherSetI getFeatureFilter(String featureType);
 227
 228   /**
 229    * Answers a shallow copy of the feature filters map
 230    *
 231    * @return
 232    */
 233   public Map<String, KeyedMatcherSetI> getFeatureFilters();
 234
 235   /**
 236    * Sets the filters for the feature type, or removes them if a null or empty
 237    * filter is passed
 238    *
 239    * @param featureType
 240    * @param filter
 241    */
 242   void setFeatureFilter(String featureType, KeyedMatcherSetI filter);
 243
 244   /**
 245    * Replaces all feature filters with the given map
 246    *
 247    * @param filters
 248    */
 249   void setFeatureFilters(Map<String, KeyedMatcherSetI> filters);
 250
 251   /**
 252    * Returns the colour for a particular feature instance. This includes
 253    * calculation of 'colour by label', or of a graduated score colour, if
 254    * applicable.
 255    * <p>
 256    * Returns null if
 257    * <ul>
 258    * <li>feature type is not visible, or</li>
 259    * <li>feature group is not visible, or</li>
 260    * <li>feature values lie outside any colour threshold, or</li>
 261    * <li>feature is excluded by filter conditions</li>
 262    * </ul>
 263    *
 264    * @param feature
 265    * @return
 266    */
 267   Color getColour(SequenceFeature feature);
 268 }