40c7d4da3c31cea81b48e91b26700a90f9dd6006
[jalview.git] / 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 }