JAL-3676 Documentation in Help for Java Console, Logging and Reporting Bugs
[jalview.git] / src / jalview / schemes / ColourSchemes.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.schemes;
22
23 import jalview.api.AlignViewportI;
24 import jalview.datamodel.AnnotatedCollectionI;
25 import jalview.datamodel.SequenceCollectionI;
26 import jalview.datamodel.SequenceI;
27
28 import java.util.LinkedHashMap;
29 import java.util.Map;
30
31 public class ColourSchemes
32 {
33   /*
34    * singleton instance of this class
35    */
36   private static ColourSchemes instance = new ColourSchemes();
37
38   /*
39    * a map from scheme name (lower-cased) to an instance of it
40    */
41   private Map<String, ColourSchemeI> schemes;
42
43   /**
44    * Returns the singleton instance of this class
45    * 
46    * @return
47    */
48   public static ColourSchemes getInstance()
49   {
50     return instance;
51   }
52
53   private ColourSchemes()
54   {
55     loadColourSchemes();
56   }
57
58   /**
59    * Loads an instance of each standard or user-defined colour scheme
60    * 
61    * @return
62    */
63   void loadColourSchemes()
64   {
65     /*
66      * store in an order-preserving map, so items can be added to menus 
67      * in the order in which they are 'discovered'
68      */
69     schemes = new LinkedHashMap<>();
70
71     for (JalviewColourScheme cs : JalviewColourScheme.values())
72     {
73       try
74       {
75         registerColourScheme(
76                 cs.getSchemeClass().getDeclaredConstructor().newInstance());
77       } catch (InstantiationException | IllegalAccessException e)
78       {
79         System.err.println("Error instantiating colour scheme for "
80                 + cs.toString() + " " + e.getMessage());
81         e.printStackTrace();
82       } catch (ReflectiveOperationException roe)
83       {
84         roe.printStackTrace();
85       }
86     }
87   }
88
89   /**
90    * Registers a colour scheme
91    * 
92    * @param cs
93    */
94   public void registerColourScheme(ColourSchemeI cs)
95   {
96     String name = cs.getSchemeName();
97     if (name == null)
98     {
99       System.err.println("ColourScheme name may not be null");
100       return;
101     }
102
103     /*
104      * name is lower-case for non-case-sensitive lookup
105      * (name in the colour keeps its true case)
106      */
107     String lower = name.toLowerCase();
108     if (schemes.containsKey(lower))
109     {
110       System.err
111               .println("Warning: overwriting colour scheme named " + name);
112     }
113     schemes.put(lower, cs);
114   }
115
116   /**
117    * Removes a colour scheme by name
118    * 
119    * @param name
120    */
121   public void removeColourScheme(String name)
122   {
123     if (name != null)
124     {
125       schemes.remove(name.toLowerCase());
126     }
127   }
128
129   /**
130    * Returns an instance of the colour scheme with which the given view may be
131    * coloured
132    * 
133    * @param name
134    *          name of the colour scheme
135    * @param viewport
136    * @param forData
137    *          the data to be coloured
138    * @param optional
139    *          map from hidden representative sequences to the sequences they
140    *          represent
141    * @return
142    */
143   public ColourSchemeI getColourScheme(String name,
144           AlignViewportI viewport, AnnotatedCollectionI forData,
145           Map<SequenceI, SequenceCollectionI> hiddenRepSequences)
146   {
147     if (name == null)
148     {
149       return null;
150     }
151     ColourSchemeI cs = schemes.get(name.toLowerCase());
152     return cs == null ? null
153             : cs.getInstance(viewport, forData);
154   }
155
156   /**
157    * Returns an instance of the colour scheme with which the given view may be
158    * coloured
159    * 
160    * @param name
161    *          name of the colour scheme
162    * @param forData
163    *          the data to be coloured
164    * @return
165    */
166   public ColourSchemeI getColourScheme(String name,
167           AnnotatedCollectionI forData)
168   {
169     return getColourScheme(name, null, forData, null);
170   }
171
172   /**
173    * Returns an iterable set of the colour schemes, in the order in which they
174    * were added
175    * 
176    * @return
177    */
178   public Iterable<ColourSchemeI> getColourSchemes()
179   {
180     return schemes.values();
181   }
182
183   /**
184    * Answers true if there is a scheme with the given name, else false. The test
185    * is not case-sensitive.
186    * 
187    * @param name
188    * @return
189    */
190   public boolean nameExists(String name)
191   {
192     if (name == null)
193     {
194       return false;
195     }
196     return schemes.containsKey(name.toLowerCase());
197   }
198 }