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 java.awt.Color;
  24 import java.awt.Graphics;
  25 import java.beans.PropertyChangeListener;
  26 import java.util.List;
  27 import java.util.Map;
  28
  29 import jalview.datamodel.MappedFeatures;
  30 import jalview.datamodel.SequenceFeature;
  31 import jalview.datamodel.SequenceI;
  32 import jalview.datamodel.features.FeatureMatcherSetI;
  33
  34 /**
  35  * Abstract feature renderer interface
  36  *
  37  * @author JimP
  38  *
  39  */
  40 public interface FeatureRenderer
  41 {
  42
  43   /**
  44    * Computes the feature colour for a given sequence and column position,
  45    * taking into account sequence feature locations, feature colour schemes,
  46    * render ordering, feature and feature group visibility, and transparency.
  47    * <p>
  48    * The graphics argument should be provided if transparency is applied
  49    * (getTransparency() < 1). With feature transparency, visible features are
  50    * written to the graphics context and the composite colour may be read off
  51    * from it. In this case, the returned feature colour is not the composite
  52    * colour but that of the last feature drawn.
  53    * <p>
  54    * If no transparency applies, then the graphics argument may be null, and the
  55    * returned colour is the one that would be drawn for the feature.
  56    * <p>
  57    * Returns null if there is no visible feature at the position.
  58    * <p>
  59    * This is provided to support rendering of feature colours other than on the
  60    * sequence alignment, including by structure viewers and the overview window.
  61    * Note this method takes no account of whether the sequence or column is
  62    * hidden.
  63    *
  64    * @param sequence
  65    * @param column
  66    *          aligned column position (1..)
  67    * @param g
  68    * @return
  69    */
  70   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
  71
  72   /**
  73    * trigger the feature discovery process for a newly created feature renderer.
  74    */
  75   void featuresAdded();
  76
  77   /**
  78    *
  79    * @param ft
  80    * @return display style for a feature
  81    */
  82   FeatureColourI getFeatureStyle(String ft);
  83
  84   /**
  85    * update the feature style for a particular feature
  86    *
  87    * @param ft
  88    * @param ggc
  89    */
  90   void setColour(String ft, FeatureColourI ggc);
  91
  92   AlignViewportI getViewport();
  93
  94   /**
  95    *
  96    * @return container managing list of feature types and their visibility
  97    */
  98   FeaturesDisplayedI getFeaturesDisplayed();
  99
 100   /**
 101    * get display style for all features types - visible or invisible
 102    *
 103    * @return
 104    */
 105   Map<String, FeatureColourI> getFeatureColours();
 106
 107   /**
 108    * query the alignment view to find all features
 109    *
 110    * @param newMadeVisible
 111    *          - when true, automatically make newly discovered types visible
 112    */
 113   void findAllFeatures(boolean newMadeVisible);
 114
 115   /**
 116    * get display style for all features types currently visible
 117    *
 118    * @return
 119    */
 120   Map<String, FeatureColourI> getDisplayedFeatureCols();
 121
 122   /**
 123    * get all registered groups
 124    *
 125    * @return
 126    */
 127   List<String> getFeatureGroups();
 128
 129   /**
 130    * get groups that are visible/invisible
 131    *
 132    * @param visible
 133    * @return
 134    */
 135   List<String> getGroups(boolean visible);
 136
 137   /**
 138    * Set visibility for a list of groups
 139    *
 140    * @param toset
 141    * @param visible
 142    */
 143   void setGroupVisibility(List<String> toset, boolean visible);
 144
 145   /**
 146    * Set visibility of the given feature group
 147    *
 148    * @param group
 149    * @param visible
 150    */
 151   void setGroupVisibility(String group, boolean visible);
 152
 153   /**
 154    * Returns visible features at the specified aligned column on the given
 155    * sequence. Non-positional features are not included. If the column has a
 156    * gap, then enclosing features are included (but not contact features).
 157    *
 158    * @param sequence
 159    * @param column
 160    *          aligned column position (1..)
 161    * @return
 162    */
 163   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence,
 164           int column);
 165
 166   /**
 167    * Returns features at the specified residue positions on the given sequence.
 168    * Non-positional features are not included. Features are returned in render
 169    * order of their feature type (last is on top). Within feature type, ordering
 170    * is undefined.
 171    *
 172    * @param sequence
 173    * @param fromResNo
 174    * @param toResNo
 175    * @return
 176    */
 177   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence,
 178           int fromResNo, int toResNo);
 179
 180   /**
 181    * get current displayed types, in ordering of rendering (on top last)
 182    *
 183    * @return a (possibly empty) list of feature types
 184    */
 185
 186   List<String> getDisplayedFeatureTypes();
 187
 188   /**
 189    * Returns a (possibly empty) list of currently visible feature groups
 190    *
 191    * @return
 192    */
 193   List<String> getDisplayedFeatureGroups();
 194
 195   /**
 196    * display all features of these types
 197    *
 198    * @param featureTypes
 199    */
 200   void setAllVisible(List<String> featureTypes);
 201
 202   /**
 203    * display featureType
 204    *
 205    * @param featureType
 206    */
 207   void setVisible(String featureType);
 208
 209   /**
 210    * Sets the transparency value, between 0 (full transparency) and 1 (no
 211    * transparency)
 212    *
 213    * @param value
 214    */
 215   void setTransparency(float value);
 216
 217   /**
 218    * Returns the transparency value, between 0 (full transparency) and 1 (no
 219    * transparency)
 220    *
 221    * @return
 222    */
 223   float getTransparency();
 224
 225   /**
 226    * Answers the filters applied to the given feature type, or null if none is
 227    * set
 228    *
 229    * @param featureType
 230    * @return
 231    */
 232   FeatureMatcherSetI getFeatureFilter(String featureType);
 233
 234   /**
 235    * Answers the feature filters map
 236    *
 237    * @return
 238    */
 239   public Map<String, FeatureMatcherSetI> getFeatureFilters();
 240
 241   /**
 242    * Sets the filters for the feature type, or removes them if a null or empty
 243    * filter is passed
 244    *
 245    * @param featureType
 246    * @param filter
 247    */
 248   void setFeatureFilter(String featureType, FeatureMatcherSetI filter);
 249
 250   /**
 251    * Replaces all feature filters with the given map
 252    *
 253    * @param filters
 254    */
 255   void setFeatureFilters(Map<String, FeatureMatcherSetI> filters);
 256
 257   /**
 258    * Returns the colour for a particular feature instance. This includes
 259    * calculation of 'colour by label', or of a graduated score colour, if
 260    * applicable.
 261    * <p>
 262    * Returns null if
 263    * <ul>
 264    * <li>feature group is not visible, or</li>
 265    * <li>feature values lie outside any colour threshold, or</li>
 266    * <li>feature is excluded by filter conditions</li>
 267    * </ul>
 268    * This method does not check feature type visibility.
 269    *
 270    * @param feature
 271    * @return
 272    */
 273   Color getColour(SequenceFeature feature);
 274
 275   /**
 276    * Answers true if feature would be shown, else false. A feature is shown if
 277    * <ul>
 278    * <li>its feature type is set to visible</li>
 279    * <li>its feature group is either null, or set to visible</li>
 280    * <li>it is not excluded by a colour threshold on score or other numeric
 281    * attribute</li>
 282    * <li>it is not excluded by a filter condition</li>
 283    * </ul>
 284    *
 285    * @param feature
 286    * @return
 287    */
 288   boolean isVisible(SequenceFeature feature);
 289
 290   /**
 291    * Answers a bean containing a mapping, and a list of visible features in this
 292    * alignment at a position (or range) which is mappable from the given
 293    * sequence residue position in a mapped alignment. Features are returned in
 294    * render order of feature type (on top last), with order within feature type
 295    * undefined. If no features or mapping are found, answers null.
 296    *
 297    * @param sequence
 298    * @param pos
 299    * @return
 300    */
 301   MappedFeatures findComplementFeaturesAtResidue(SequenceI sequence,
 302           int pos);
 303
 304   /**
 305    * Sends a message to let any registered parties know that something about
 306    * feature rendering has changed
 307    */
 308   void notifyFeaturesChanged();
 309
 310   /**
 311    * register as a listener for notifyFeaturesChanged events
 312    *
 313    * @param ourListener
 314    */
 315   void addPropertyChangeListener(PropertyChangeListener ourListener);
 316
 317   /**
 318    * remove a listener for notifyFeaturesChanged events
 319    *
 320    * @param ourListener
 321    */
 322   void removePropertyChangeListener(PropertyChangeListener ourListener);
 323
 324   /**
 325    *
 326    * @return associated alignment panel for this feature renderer (may return
 327    *         null)
 328    */
 329   AlignmentViewPanel getAlignPanel();
 330
 331 }