JAL-518 refactored groovy script into main codebase as an Edit Command and alignment...
[jalview.git] / src / jalview / api / AlignViewportI.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.Font;
25 import java.util.Hashtable;
26 import java.util.Iterator;
27 import java.util.List;
28 import java.util.Map;
29
30 import jalview.analysis.Conservation;
31 import jalview.analysis.TreeModel;
32 import jalview.datamodel.AlignmentAnnotation;
33 import jalview.datamodel.AlignmentExportData;
34 import jalview.datamodel.AlignmentI;
35 import jalview.datamodel.AlignmentView;
36 import jalview.datamodel.ColumnSelection;
37 import jalview.datamodel.ProfilesI;
38 import jalview.datamodel.SearchResultsI;
39 import jalview.datamodel.SequenceCollectionI;
40 import jalview.datamodel.SequenceGroup;
41 import jalview.datamodel.SequenceI;
42 import jalview.renderer.ResidueShaderI;
43 import jalview.schemes.ColourSchemeI;
44 import jalview.viewmodel.ViewportRanges;
45
46 /**
47  * @author jimp
48  * 
49  */
50 public interface AlignViewportI extends ViewStyleI
51 {
52
53   /**
54    * Get the ranges object containing details of the start and end sequences and
55    * residues
56    * 
57    * @return
58    */
59   public ViewportRanges getRanges();
60
61   /**
62    * calculate the height for visible annotation, revalidating bounds where
63    * necessary ABSTRACT GUI METHOD
64    * 
65    * @return total height of annotation
66    */
67   public int calcPanelHeight();
68
69   /**
70    * Answers true if the viewport has at least one column selected
71    * 
72    * @return
73    */
74   boolean hasSelectedColumns();
75
76   /**
77    * Answers true if the viewport has at least one hidden column
78    * 
79    * @return
80    */
81   boolean hasHiddenColumns();
82
83   boolean isValidCharWidth();
84
85   boolean isShowConsensusHistogram();
86
87   boolean isShowSequenceLogo();
88
89   boolean isNormaliseSequenceLogo();
90
91   ColourSchemeI getGlobalColourScheme();
92
93   /**
94    * Returns an object that describes colouring (including any thresholding or
95    * fading) of the alignment
96    * 
97    * @return
98    */
99   ResidueShaderI getResidueShading();
100
101   AlignmentI getAlignment();
102
103   ColumnSelection getColumnSelection();
104
105   ProfilesI getSequenceConsensusHash();
106
107   /**
108    * Get consensus data table for the cDNA complement of this alignment (if any)
109    * 
110    * @return
111    */
112   Hashtable<String, Object>[] getComplementConsensusHash();
113
114   Hashtable<String, Object>[] getRnaStructureConsensusHash();
115
116   boolean isIgnoreGapsConsensus();
117
118   boolean isCalculationInProgress(AlignmentAnnotation alignmentAnnotation);
119
120   AlignmentAnnotation getAlignmentQualityAnnot();
121
122   AlignmentAnnotation getAlignmentConservationAnnotation();
123
124   /**
125    * get the container for alignment consensus annotation
126    * 
127    * @return
128    */
129   AlignmentAnnotation getAlignmentConsensusAnnotation();
130
131   /**
132    * get the container for alignment gap annotation
133    * 
134    * @return
135    */
136   AlignmentAnnotation getAlignmentGapAnnotation();
137
138   /**
139    * get the container for cDNA complement consensus annotation
140    * 
141    * @return
142    */
143   AlignmentAnnotation getComplementConsensusAnnotation();
144
145   /**
146    * Test to see if viewport is still open and active
147    * 
148    * @return true indicates that all references to viewport should be dropped
149    */
150   boolean isClosed();
151
152   /**
153    * Dispose of all references or resources held by the viewport
154    */
155   void dispose();
156
157   /**
158    * get the associated calculation thread manager for the view
159    * 
160    * @return
161    */
162   AlignCalcManagerI getCalcManager();
163
164   /**
165    * get the percentage gaps allowed in a conservation calculation
166    * 
167    */
168   public int getConsPercGaps();
169
170   /**
171    * set the consensus result object for the viewport
172    * 
173    * @param hconsensus
174    */
175   void setSequenceConsensusHash(ProfilesI hconsensus);
176
177   /**
178    * Set the cDNA complement consensus for the viewport
179    * 
180    * @param hconsensus
181    */
182   void setComplementConsensusHash(Hashtable<String, Object>[] hconsensus);
183
184   /**
185    * 
186    * @return the alignment annotation row for the structure consensus
187    *         calculation
188    */
189   AlignmentAnnotation getAlignmentStrucConsensusAnnotation();
190
191   /**
192    * set the Rna structure consensus result object for the viewport
193    * 
194    * @param hStrucConsensus
195    */
196   void setRnaStructureConsensusHash(
197           Hashtable<String, Object>[] hStrucConsensus);
198
199   /**
200    * Sets the colour scheme for the background alignment (as distinct from
201    * sub-groups, which may have their own colour schemes). A null value is used
202    * for no residue colour (white).
203    * 
204    * @param cs
205    */
206   void setGlobalColourScheme(ColourSchemeI cs);
207
208   Map<SequenceI, SequenceCollectionI> getHiddenRepSequences();
209
210   void setHiddenRepSequences(
211           Map<SequenceI, SequenceCollectionI> hiddenRepSequences);
212
213   /**
214    * hides or shows dynamic annotation rows based on groups and group and
215    * alignment associated auto-annotation state flags apply the current
216    * group/autoannotation settings to the alignment view. Usually you should
217    * call the AlignmentViewPanel.adjustAnnotationHeight() method afterwards to
218    * ensure the annotation panel bounds are set correctly.
219    * 
220    * @param applyGlobalSettings
221    *          - apply to all autoannotation rows or just the ones associated
222    *          with the current visible region
223    * @param preserveNewGroupSettings
224    *          - don't apply global settings to groups which don't already have
225    *          group associated annotation
226    */
227   void updateGroupAnnotationSettings(boolean applyGlobalSettings,
228           boolean preserveNewGroupSettings);
229
230   void setSequenceColour(SequenceI seq, Color col);
231
232   Color getSequenceColour(SequenceI seq);
233
234   void updateSequenceIdColours();
235
236   SequenceGroup getSelectionGroup();
237
238   /**
239    * get the currently selected sequence objects or all the sequences in the
240    * alignment. TODO: change to List<>
241    * 
242    * @return array of references to sequence objects
243    */
244   SequenceI[] getSequenceSelection();
245
246   void clearSequenceColours();
247
248   /**
249    * return a compact representation of the current alignment selection to pass
250    * to an analysis function
251    * 
252    * @param selectedOnly
253    *          boolean true to just return the selected view
254    * @return AlignmentView
255    */
256   AlignmentView getAlignmentView(boolean selectedOnly);
257
258   /**
259    * return a compact representation of the current alignment selection to pass
260    * to an analysis function
261    * 
262    * @param selectedOnly
263    *          boolean true to just return the selected view
264    * @param markGroups
265    *          boolean true to annotate the alignment view with groups on the
266    *          alignment (and intersecting with selected region if selectedOnly
267    *          is true)
268    * @return AlignmentView
269    */
270   AlignmentView getAlignmentView(boolean selectedOnly, boolean markGroups);
271
272   /**
273    * This method returns the visible alignment as text, as seen on the GUI, ie
274    * if columns are hidden they will not be returned in the result. Use this for
275    * calculating trees, PCA, redundancy etc on views which contain hidden
276    * columns. This method doesn't exclude hidden sequences from the output.
277    *
278    * @param selectedRegionOnly
279    *          - determines if only the selected region or entire alignment is
280    *          exported
281    * @return String[]
282    */
283   String[] getViewAsString(boolean selectedRegionOnly);
284
285   /**
286    * This method returns the visible alignment as text, as seen on the GUI, ie
287    * if columns are hidden they will not be returned in the result. Use this for
288    * calculating trees, PCA, redundancy etc on views which contain hidden
289    * columns.
290    * 
291    * @param selectedRegionOnly
292    *          - determines if only the selected region or entire alignment is
293    *          exported
294    * @param isExportHiddenSeqs
295    *          - determines if hidden sequences would be exported or not.
296    * 
297    * @return String[]
298    */
299   String[] getViewAsString(boolean selectedRegionOnly,
300           boolean isExportHiddenSeqs);
301
302   void setSelectionGroup(SequenceGroup sg);
303
304   char getGapCharacter();
305
306   void setColumnSelection(ColumnSelection cs);
307
308   void setConservation(Conservation cons);
309
310   /**
311    * get a copy of the currently visible alignment annotation
312    * 
313    * @param selectedOnly
314    *          if true - trim to selected regions on the alignment
315    * @return an empty list or new alignment annotation objects shown only
316    *         visible columns trimmed to selected region only
317    */
318   List<AlignmentAnnotation> getVisibleAlignmentAnnotation(
319           boolean selectedOnly);
320
321   FeaturesDisplayedI getFeaturesDisplayed();
322
323   String getSequenceSetId();
324
325   boolean areFeaturesDisplayed();
326
327   void setFeaturesDisplayed(FeaturesDisplayedI featuresDisplayedI);
328
329   void alignmentChanged(AlignmentViewPanel ap);
330
331   /**
332    * @return the padGaps
333    */
334   boolean isPadGaps();
335
336   /**
337    * @param padGaps
338    *          the padGaps to set
339    */
340   void setPadGaps(boolean padGaps);
341
342   /**
343    * return visible region boundaries within given column range
344    * 
345    * @param min
346    *          first column (inclusive, from 0)
347    * @param max
348    *          last column (exclusive)
349    * @return int[][] range of {start,end} visible positions
350    */
351   List<int[]> getVisibleRegionBoundaries(int min, int max);
352
353   /**
354    * This method returns an array of new SequenceI objects derived from the
355    * whole alignment or just the current selection with start and end points
356    * adjusted
357    * 
358    * @note if you need references to the actual SequenceI objects in the
359    *       alignment or currently selected then use getSequenceSelection()
360    * @return selection as new sequenceI objects
361    */
362   SequenceI[] getSelectionAsNewSequence();
363
364   void invertColumnSelection();
365
366   /**
367    * broadcast selection to any interested parties
368    */
369   void sendSelection();
370
371   /**
372    * calculate the row position for alignmentIndex if all hidden sequences were
373    * shown
374    * 
375    * @param alignmentIndex
376    * @return adjusted row position
377    */
378   int adjustForHiddenSeqs(int alignmentIndex);
379
380   boolean hasHiddenRows();
381
382   /**
383    * 
384    * @return a copy of this view's current display settings
385    */
386   public ViewStyleI getViewStyle();
387
388   /**
389    * update the view's display settings with the given style set
390    * 
391    * @param settingsForView
392    */
393   public void setViewStyle(ViewStyleI settingsForView);
394
395   /**
396    * Returns a viewport which holds the cDna for this (protein), or vice versa,
397    * or null if none is set.
398    * 
399    * @return
400    */
401   AlignViewportI getCodingComplement();
402
403   /**
404    * Sets the viewport which holds the cDna for this (protein), or vice versa.
405    * Implementation should guarantee that the reciprocal relationship is always
406    * set, i.e. each viewport is the complement of the other.
407    */
408   void setCodingComplement(AlignViewportI sl);
409
410   /**
411    * Answers true if viewport hosts DNA/RNA, else false.
412    * 
413    * @return
414    */
415   boolean isNucleotide();
416
417   /**
418    * Returns an id guaranteed to be unique for this viewport.
419    * 
420    * @return
421    */
422   String getViewId();
423
424   /**
425    * Return true if view should scroll to show the highlighted region of a
426    * sequence
427    * 
428    * @return
429    */
430   boolean isFollowHighlight();
431
432   /**
433    * Set whether view should scroll to show the highlighted region of a sequence
434    */
435   void setFollowHighlight(boolean b);
436
437   /**
438    * configure the feature renderer with predefined feature settings
439    * 
440    * @param featureSettings
441    */
442   public void applyFeaturesStyle(FeatureSettingsModelI featureSettings);
443
444   /**
445    * Apply the given feature settings on top of existing feature settings.
446    */
447   public void mergeFeaturesStyle(FeatureSettingsModelI featureSettings);
448
449   /**
450    * check if current selection group is defined on the view, or is simply a
451    * temporary group.
452    * 
453    * @return true if group is defined on the alignment
454    */
455   boolean isSelectionDefinedGroup();
456
457   /**
458    * 
459    * @return true if there are search results on the view
460    */
461   boolean hasSearchResults();
462
463   /**
464    * set the search results for the view
465    * 
466    * @param results
467    *          - or null to clear current results
468    */
469   void setSearchResults(SearchResultsI results);
470
471   /**
472    * get search results for this view (if any)
473    * 
474    * @return search results or null
475    */
476   SearchResultsI getSearchResults();
477
478   /**
479    * Updates view settings with the given font. You may need to call
480    * AlignmentPanel.fontChanged to update the layout geometry.
481    * 
482    * @param setGrid
483    *          when true, charWidth/height is set according to font metrics
484    */
485   void setFont(Font newFont, boolean b);
486
487   /**
488    * Answers true if split screen protein and cDNA use the same font
489    * 
490    * @return
491    */
492   @Override
493   boolean isProteinFontAsCdna();
494
495   /**
496    * Set the flag for whether split screen protein and cDNA use the same font
497    * 
498    * @return
499    */
500   @Override
501   void setProteinFontAsCdna(boolean b);
502
503   TreeModel getCurrentTree();
504
505   void setCurrentTree(TreeModel tree);
506
507   /**
508    * Answers a data bean containing data for export as configured by the
509    * supplied options
510    * 
511    * @param options
512    * @return
513    */
514   AlignmentExportData getAlignExportData(AlignExportSettingsI options);
515
516   /**
517    * @param update
518    *          - set the flag for updating structures on next repaint
519    */
520   void setUpdateStructures(boolean update);
521
522   /**
523    *
524    * @return true if structure views will be updated on next refresh
525    */
526   boolean isUpdateStructures();
527
528   /**
529    * check if structure views need to be updated, and clear the flag afterwards.
530    * 
531    * @return if an update is needed
532    */
533   boolean needToUpdateStructureViews();
534
535   /**
536    * Adds sequencegroup to the alignment in the view. Also adds a group to the
537    * complement view if one is defined.
538    * 
539    * @param sequenceGroup
540    *          - a group defined on sequences in the alignment held by the view
541    */
542   void addSequenceGroup(SequenceGroup sequenceGroup);
543
544   /**
545    * Returns an interator over the [start, end] column positions of the visible
546    * regions of the alignment
547    * 
548    * @param selectedRegionOnly
549    *          if true, and the view has a selection region, then only the
550    *          intersection of visible columns with the selection region is
551    *          returned
552    * @return
553    */
554   Iterator<int[]> getViewAsVisibleContigs(boolean selectedRegionOnly);
555
556   /**
557    * notify all concerned that the alignment data has changed and derived data
558    * needs to be recalculated
559    */
560   public void notifyAlignmentChanged();
561 }