Merge branch 'releases/Release_2_11_4_Branch'
[jalview.git] / 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
26 import java.awt.Color;
27 import java.awt.Graphics;
28 import java.util.List;
29 import java.util.Map;
30
31 /**
32  * Abstract feature renderer interface
33  * 
34  * @author JimP
35  * 
36  */
37 public interface FeatureRenderer
38 {
39
40   /**
41    * Computes the feature colour for a given sequence and column position,
42    * taking into account sequence feature locations, feature colour schemes,
43    * render ordering, feature and feature group visibility, and transparency.
44    * <p>
45    * The graphics argument should be provided if transparency is applied
46    * (getTransparency() < 1). With feature transparency, visible features are
47    * written to the graphics context and the composite colour may be read off
48    * from it. In this case, the returned feature colour is not the composite
49    * colour but that of the last feature drawn.
50    * <p>
51    * If no transparency applies, then the graphics argument may be null, and the
52    * returned colour is the one that would be drawn for the feature.
53    * <p>
54    * Returns null if there is no visible feature at the position.
55    * <p>
56    * This is provided to support rendering of feature colours other than on the
57    * sequence alignment, including by structure viewers and the overview window.
58    * Note this method takes no account of whether the sequence or column is
59    * hidden.
60    * 
61    * @param sequence
62    * @param column
63    * @param g
64    * @return
65    */
66   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
67
68   /**
69    * trigger the feature discovery process for a newly created feature renderer.
70    */
71   void featuresAdded();
72
73   /**
74    * 
75    * @param ft
76    * @return display style for a feature
77    */
78   FeatureColourI getFeatureStyle(String ft);
79
80   /**
81    * update the feature style for a particular feature
82    * 
83    * @param ft
84    * @param ggc
85    */
86   void setColour(String ft, FeatureColourI ggc);
87
88   AlignViewportI getViewport();
89
90   /**
91    * 
92    * @return container managing list of feature types and their visibility
93    */
94   FeaturesDisplayedI getFeaturesDisplayed();
95
96   /**
97    * get display style for all features types - visible or invisible
98    * 
99    * @return
100    */
101   Map<String, FeatureColourI> getFeatureColours();
102
103   /**
104    * query the alignment view to find all features
105    * 
106    * @param newMadeVisible
107    *          - when true, automatically make newly discovered types visible
108    */
109   void findAllFeatures(boolean newMadeVisible);
110
111   /**
112    * get display style for all features types currently visible
113    * 
114    * @return
115    */
116   Map<String, FeatureColourI> getDisplayedFeatureCols();
117
118   /**
119    * get all registered groups
120    * 
121    * @return
122    */
123   List<String> getFeatureGroups();
124
125   /**
126    * get groups that are visible/invisible
127    * 
128    * @param visible
129    * @return
130    */
131   List<String> getGroups(boolean visible);
132
133   /**
134    * change visibility for a range of groups
135    * 
136    * @param toset
137    * @param visible
138    */
139   void setGroupVisibility(List<String> toset, boolean visible);
140
141   /**
142    * change visibiilty of given group
143    * 
144    * @param group
145    * @param visible
146    */
147   void setGroupVisibility(String group, boolean visible);
148
149   /**
150    * Returns features at the specified position on the given sequence.
151    * Non-positional features are not included.
152    * 
153    * @param sequence
154    * @param res
155    * @return
156    */
157   List<SequenceFeature> findFeaturesAtRes(SequenceI sequence, int res);
158
159   /**
160    * get current displayed types, in ordering of rendering (on top last)
161    * 
162    * @return a (possibly empty) list of feature types
163    */
164
165   List<String> getDisplayedFeatureTypes();
166
167   /**
168    * get current displayed groups
169    * 
170    * @return a (possibly empty) list of feature groups
171    */
172   List<String> getDisplayedFeatureGroups();
173
174   /**
175    * display all features of these types
176    * 
177    * @param featureTypes
178    */
179   void setAllVisible(List<String> featureTypes);
180
181   /**
182    * display featureType
183    * 
184    * @param featureType
185    */
186   void setVisible(String featureType);
187
188   /**
189    * Sets the transparency value, between 0 (full transparency) and 1 (no
190    * transparency)
191    * 
192    * @param value
193    */
194   void setTransparency(float value);
195
196   /**
197    * Returns the transparency value, between 0 (full transparency) and 1 (no
198    * transparency)
199    * 
200    * @return
201    */
202   float getTransparency();
203 }