JAL-4034 fix 1 - reword button
[jalview.git] / src / jalview / structure / StructureCommandsI.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.structure;
22
23 import java.awt.Color;
24 import java.util.List;
25 import java.util.Map;
26
27 /**
28  * Methods that generate commands that can be sent to a molecular structure
29  * viewer program (e.g. Jmol, Chimera, ChimeraX)
30  * 
31  * @author gmcarstairs
32  *
33  */
34 public interface StructureCommandsI
35 {
36   /**
37    * Returns the command to colour by chain
38    * 
39    * @return
40    */
41   StructureCommandI colourByChain();
42
43   /**
44    * Returns the command to colour residues using a charge-based scheme:
45    * <ul>
46    * <li>Aspartic acid and Glutamic acid (negative charge) red</li>
47    * <li>Lysine and Arginine (positive charge) blue</li>
48    * <li>Cysteine - yellow</li>
49    * <li>all others - white</li>
50    * </ul>
51    * 
52    * @return
53    */
54   List<StructureCommandI> colourByCharge();
55
56   /**
57    * Returns the command to colour residues with the colours provided in the
58    * map, one per three letter residue code
59    * 
60    * @param colours
61    * @return
62    */
63   List<StructureCommandI> colourByResidues(Map<String, Color> colours);
64
65   /**
66    * Returns the command to set the background colour of the structure viewer
67    * 
68    * @param col
69    * @return
70    */
71   StructureCommandI setBackgroundColour(Color col);
72
73   /**
74    * Returns commands to colour mapped residues of structures according to
75    * Jalview's colouring (including feature colouring if applied). Parameter is
76    * a map from Color to a model of all residues assigned that colour.
77    * 
78    * @param colourMap
79    * @return
80    */
81
82   List<StructureCommandI> colourBySequence(
83           Map<Object, AtomSpecModel> colourMap);
84
85   /**
86    * Returns a command to centre the display in the structure viewer
87    * 
88    * @return
89    */
90   StructureCommandI focusView();
91
92   /**
93    * Returns a command to show only the selected chains. The items in the input
94    * list should be formatted as "modelid:chainid".
95    * 
96    * @param toShow
97    * @return
98    */
99   List<StructureCommandI> showChains(List<String> toShow);
100
101   /**
102    * Returns a command to superpose structures by closest positioning of
103    * residues in {@code atomSpec} to the corresponding residues in
104    * {@code refAtoms}. If wanted, this may include commands to visually
105    * highlight the residues that were used for the superposition.
106    * 
107    * @param refAtoms
108    * @param atomSpec
109    * @param backbone
110    *          - superpose based on which kind of atomType
111    * @return
112    */
113   List<StructureCommandI> superposeStructures(AtomSpecModel refAtoms,
114           AtomSpecModel atomSpec, AtomSpecType backbone);
115
116   /**
117    * Returns a command to open a file of commands at the given path
118    * 
119    * @param path
120    * @return
121    */
122   StructureCommandI openCommandFile(String path);
123
124   /**
125    * Returns a command to save the current viewer session state to the given
126    * file
127    * 
128    * @param filepath
129    * @return
130    */
131   StructureCommandI saveSession(String filepath);
132
133   enum AtomSpecType
134   {
135     RESIDUE_ONLY, ALPHA, PHOSPHATE
136   };
137
138   /**
139    * Returns a representation of the atom set represented by the model, in
140    * viewer syntax format. If {@code alphaOnly} is true, this is restricted to
141    * Alpha Carbon (peptide) or Phosphorous (rna) only
142    * 
143    * @param model
144    * @param specType
145    * @return
146    */
147   String getAtomSpec(AtomSpecModel model, AtomSpecType specType);
148
149   /**
150    * Returns the lowest model number used by the structure viewer (likely 0 or
151    * 1)
152    * 
153    * @return
154    */
155   // TODO remove by refactoring so command generation is purely driven by
156   // AtomSpecModel objects derived in the binding classes?
157   int getModelStartNo();
158
159   /**
160    * Returns command(s) to show only the backbone of the peptide (cartoons in
161    * Jmol, chain in Chimera)
162    * 
163    * @return
164    */
165   List<StructureCommandI> showBackbone();
166
167   /**
168    * Returns a command to open a file at the given path
169    * 
170    * @param file
171    * @return
172    */
173   // refactor if needed to distinguish loading data or session files
174   StructureCommandI loadFile(String file);
175
176   /**
177    * Returns commands to set atom attributes or properties, given a map of
178    * Jalview features as {featureType, {featureValue, AtomSpecModel}}. The
179    * assumption is that one command can be constructed for each feature type and
180    * value combination, to apply it to one or more residues.
181    * 
182    * @param featureValues
183    * @return
184    */
185   List<StructureCommandI> setAttributes(
186           Map<String, Map<Object, AtomSpecModel>> featureValues);
187
188   /**
189    * Returns command to open a saved structure viewer session file, or null if
190    * not supported
191    * 
192    * @param filepath
193    * @return
194    */
195   StructureCommandI openSession(String filepath);
196
197   /**
198    * Returns a command to ask the viewer to close down
199    * 
200    * @return
201    */
202   StructureCommandI closeViewer();
203
204   /**
205    * Returns one or more commands to ask the viewer to notify model or selection
206    * changes to the given uri. Returns null if this is not supported by the
207    * structure viewer.
208    * 
209    * @param uri
210    * @return
211    */
212   List<StructureCommandI> startNotifications(String uri);
213
214   /**
215    * Returns one or more commands to ask the viewer to stop notifying model or
216    * selection changes. Returns null if this is not supported by the structure
217    * viewer.
218    * 
219    * @return
220    */
221   List<StructureCommandI> stopNotifications();
222
223   /**
224    * Returns a command to ask the viewer for its current residue selection, or
225    * null if no such command is supported
226    * 
227    * @return
228    */
229   StructureCommandI getSelectedResidues();
230
231   /**
232    * Returns a command to list the unique names of residue attributes, or null
233    * if no such command is supported
234    * 
235    * @return
236    */
237   StructureCommandI listResidueAttributes();
238
239   /**
240    * Returns a command to list residues with an attribute of the given name,
241    * with attribute value, or null if no such command is supported
242    * 
243    * @return
244    */
245   StructureCommandI getResidueAttributes(String attName);
246 }