src/jalview/api/FeatureColourI.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
  25 import java.awt.Color;
  26
  27 public interface FeatureColourI
  28 {
  29
  30   /**
  31    * Answers true when the feature colour varies across the score range
  32    *
  33    * @return
  34    */
  35   boolean isGraduatedColour();
  36
  37   /**
  38    * Returns the feature colour (when isGraduatedColour answers false)
  39    *
  40    * @return
  41    */
  42   Color getColour();
  43
  44   /**
  45    * Returns the minimum colour (when isGraduatedColour answers true)
  46    *
  47    * @return
  48    */
  49   Color getMinColour();
  50
  51   /**
  52    * Returns the maximum colour (when isGraduatedColour answers true)
  53    *
  54    * @return
  55    */
  56   Color getMaxColour();
  57
  58   /**
  59    * Returns the 'no value' colour (used when a feature lacks score, or the
  60    * attribute, being used for colouring)
  61    *
  62    * @return
  63    */
  64   Color getNoColour();
  65
  66   /**
  67    * Answers true if the feature has a single colour, i.e. if isColourByLabel()
  68    * and isGraduatedColour() both answer false
  69    *
  70    * @return
  71    */
  72   boolean isSimpleColour();
  73
  74   /**
  75    * Answers true if the feature is coloured by label (description) or by text
  76    * value of an attribute
  77    *
  78    * @return
  79    */
  80   boolean isColourByLabel();
  81
  82   void setColourByLabel(boolean b);
  83
  84   /**
  85    * Answers true if the feature is coloured below a threshold value; only
  86    * applicable when isGraduatedColour answers true
  87    *
  88    * @return
  89    */
  90   boolean isBelowThreshold();
  91
  92   void setBelowThreshold(boolean b);
  93
  94   /**
  95    * Answers true if the feature is coloured above a threshold value; only
  96    * applicable when isGraduatedColour answers true
  97    *
  98    * @return
  99    */
 100   boolean isAboveThreshold();
 101
 102   void setAboveThreshold(boolean b);
 103
 104   /**
 105    * Returns the threshold value (if any), else zero
 106    *
 107    * @return
 108    */
 109   float getThreshold();
 110
 111   void setThreshold(float f);
 112
 113   /**
 114    * Answers true if the colour varies between the actual minimum and maximum
 115    * score values of the feature, or false if between absolute minimum and
 116    * maximum values (or if not a graduated colour).
 117    *
 118    * @return
 119    */
 120   boolean isAutoScaled();
 121
 122   void setAutoScaled(boolean b);
 123
 124   /**
 125    * Returns the maximum score of the graduated colour range
 126    *
 127    * @return
 128    */
 129   float getMax();
 130
 131   /**
 132    * Returns the minimum score of the graduated colour range
 133    *
 134    * @return
 135    */
 136   float getMin();
 137
 138   /**
 139    * Answers true if either isAboveThreshold or isBelowThreshold answers true
 140    *
 141    * @return
 142    */
 143   boolean hasThreshold();
 144
 145   /**
 146    * Returns the computed colour for the given sequence feature. Answers null if
 147    * the score of this feature instance is outside the range to render (if any),
 148    * i.e. lies below or above a configured threshold.
 149    *
 150    * @param feature
 151    * @return
 152    */
 153   Color getColor(SequenceFeature feature);
 154
 155   /**
 156    * Update the min-max range for a graduated colour scheme. Note that the
 157    * colour scheme may be configured to colour by feature score, or a
 158    * (numeric-valued) attribute - the caller should ensure that the correct
 159    * range is being set.
 160    *
 161    * @param min
 162    * @param max
 163    */
 164   void updateBounds(float min, float max);
 165
 166   /**
 167    * Returns the colour in Jalview features file format
 168    *
 169    * @return
 170    */
 171   String toJalviewFormat(String featureType);
 172
 173   /**
 174    * Answers true if colour is by attribute text or numerical value
 175    *
 176    * @return
 177    */
 178   boolean isColourByAttribute();
 179
 180   /**
 181    * Answers the name of the attribute (and optional sub-attribute...) used for
 182    * colouring if any, or null
 183    *
 184    * @return
 185    */
 186   String[] getAttributeName();
 187
 188   /**
 189    * Sets the name of the attribute (and optional sub-attribute...) used for
 190    * colouring if any, or null to remove this property
 191    *
 192    * @return
 193    */
 194   void setAttributeName(String... name);
 195
 196   /**
 197    * Answers true if colour has a threshold set, and the feature score (or other
 198    * attribute selected for colouring) is outwith the threshold.
 199    * <p>
 200    * Answers false if not a graduated colour, or no threshold is set, or value
 201    * is not outwith the threshold, or value is null or non-numeric.
 202    *
 203    * @param sf
 204    * @return
 205    */
 206   boolean isOutwithThreshold(SequenceFeature sf);
 207
 208   /*
 209    * Answers a human-readable text description of the colour, suitable for
 210    * display as a tooltip, possibly internationalised for the user's locale.
 211    *
 212    * @return
 213    */
 214   String getDescription();
 215 }