JAL-2788 possible adjustments to sequence accesses
[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
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    *          aligned column position (1..)
64    * @param g
65    * @return
66    */
67   Color findFeatureColour(SequenceI sequence, int column, Graphics g);
68
69   /**
70    * trigger the feature discovery process for a newly created feature renderer.
71    */
72   void featuresAdded();
73
74   /**
75    * 
76    * @param ft
77    * @return display style for a feature
78    */
79   FeatureColourI getFeatureStyle(String ft);
80
81   /**
82    * update the feature style for a particular feature
83    * 
84    * @param ft
85    * @param ggc
86    */
87   void setColour(String ft, FeatureColourI ggc);
88
89   AlignViewportI getViewport();
90
91   /**
92    * 
93    * @return container managing list of feature types and their visibility
94    */
95   FeaturesDisplayedI getFeaturesDisplayed();
96
97   /**
98    * get display style for all features types - visible or invisible
99    * 
100    * @return
101    */
102   Map<String, FeatureColourI> getFeatureColours();
103
104   /**
105    * query the alignment view to find all features
106    * 
107    * @param newMadeVisible
108    *          - when true, automatically make newly discovered types visible
109    */
110   void findAllFeatures(boolean newMadeVisible);
111
112   /**
113    * get display style for all features types currently visible
114    * 
115    * @return
116    */
117   Map<String, FeatureColourI> getDisplayedFeatureCols();
118
119   /**
120    * get all registered groups
121    * 
122    * @return
123    */
124   List<String> getFeatureGroups();
125
126   /**
127    * get groups that are visible/invisible
128    * 
129    * @param visible
130    * @return
131    */
132   List<String> getGroups(boolean visible);
133
134   /**
135    * change visibility for a range of groups
136    * 
137    * @param toset
138    * @param visible
139    */
140   void setGroupVisibility(List<String> toset, boolean visible);
141
142   /**
143    * change visibiilty of given group
144    * 
145    * @param group
146    * @param visible
147    */
148   void setGroupVisibility(String group, boolean visible);
149
150   /**
151    * Returns features at the specified aligned column on the given sequence.
152    * Non-positional features are not included. If the column has a gap, then
153    * enclosing features are included (but not contact features).
154    * 
155    * @param sequence
156    * @param column
157    *          aligned column position (1..)
158    * @return
159    */
160   List<SequenceFeature> findFeaturesAtColumn(SequenceI sequence, int column);
161
162   /**
163    * Returns features at the specified residue position on the given sequence.
164    * Non-positional features are not included.
165    * 
166    * @param sequence
167    * @param resNo
168    *          residue position (start..)
169    * @return
170    */
171   List<SequenceFeature> findFeaturesAtResidue(SequenceI sequence, int resNo);
172
173   /**
174    * get current displayed types, in ordering of rendering (on top last)
175    * 
176    * @return a (possibly empty) list of feature types
177    */
178
179   List<String> getDisplayedFeatureTypes();
180
181   /**
182    * Returns a (possibly empty) list of currently visible feature groups
183    * 
184    * @return
185    */
186   List<String> getDisplayedFeatureGroups();
187
188   /**
189    * display all features of these types
190    * 
191    * @param featureTypes
192    */
193   void setAllVisible(List<String> featureTypes);
194
195   /**
196    * display featureType
197    * 
198    * @param featureType
199    */
200   void setVisible(String featureType);
201
202   /**
203    * Sets the transparency value, between 0 (full transparency) and 1 (no
204    * transparency)
205    * 
206    * @param value
207    */
208   void setTransparency(float value);
209
210   /**
211    * Returns the transparency value, between 0 (full transparency) and 1 (no
212    * transparency)
213    * 
214    * @return
215    */
216   float getTransparency();
217
218 }