JAL-2416 order score models by order of addition rather than name
[jalview.git] / src / jalview / javascript / JalviewLiteJsApi.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.javascript;
22
23 import jalview.appletgui.AlignFrame;
24
25 /**
26  * The following public methods may be called
27  * externally, eg via javascript in an HTML page.
28  * 
29  * <br><em>TODO: introduce abstract interface for jalview.appletgui.AlignFrame</em><br>
30  * 
31  * Most function arguments are strings, which contain serialised versions of lists.
32  * Lists of things are separated by a separator character - either the default or a user supplied one.
33  * Ranges and positions on an alignment or sequence can be specified as a list, where an item containing a single number is a single position, and an item like 1-2 specifies columns 1 and 2 as a range.
34  */
35
36 /**
37  * @author jimp
38  * 
39  */
40 public interface JalviewLiteJsApi
41 {
42
43   /**
44    * @return String list of selected sequence IDs, each terminated by the
45    *         'boolean not' character (""+0x00AC) or (&#172;)
46    */
47   public abstract String getSelectedSequences();
48
49   /**
50    * @param sep
51    *          separator string or null for default
52    * @return String list of selected sequence IDs, each terminated by given
53    *         separator string
54    */
55   public abstract String getSelectedSequences(String sep);
56
57   /**
58    * @param alf
59    *          alignframe containing selection
60    * @return String list of selected sequence IDs, each terminated by current
61    *         default separator sequence
62    * 
63    */
64   public abstract String getSelectedSequencesFrom(AlignFrame alf);
65
66   /**
67    * get list of selected sequence IDs separated by given separator
68    * 
69    * @param alf
70    *          window containing selection
71    * @param sep
72    *          separator string to use - default is 'boolean not'
73    * @return String list of selected sequence IDs, each terminated by the given
74    *         separator
75    */
76   public abstract String getSelectedSequencesFrom(AlignFrame alf, String sep);
77
78   /**
79    * 
80    * @param sequenceId
81    *          id of sequence to highlight
82    * @param position
83    *          integer position [ tobe implemented or range ] on sequence
84    * @param alignedPosition
85    *          true/false/empty string - indicate if position is an alignment
86    *          column or unaligned sequence position
87    */
88   public abstract void highlight(String sequenceId, String position,
89           String alignedPosition);
90
91   /**
92    * 
93    * @param sequenceId
94    *          id of sequence to highlight
95    * @param position
96    *          integer position [ tobe implemented or range ] on sequence
97    * @param alignedPosition
98    *          false, blank or something else - indicate if position is an
99    *          alignment column or unaligned sequence position
100    */
101   public abstract void highlightIn(AlignFrame alf, String sequenceId,
102           String position, String alignedPosition);
103
104   /**
105    * select regions of the currrent alignment frame
106    * 
107    * @param sequenceIds
108    *          String separated list of sequence ids or empty string
109    * @param columns
110    *          String separated list { column range or column, ..} or empty
111    *          string
112    */
113   public abstract void select(String sequenceIds, String columns);
114
115   /**
116    * select regions of the currrent alignment frame
117    * 
118    * @param toselect
119    *          String separated list { column range, seq1...seqn sequence ids }
120    * @param sep
121    *          separator between toselect fields
122    */
123   public abstract void select(String sequenceIds, String columns, String sep);
124
125   /**
126    * select regions of the given alignment frame
127    * 
128    * @param alf
129    * @param toselect
130    *          String separated list { column range, seq1...seqn sequence ids }
131    * @param sep
132    *          separator between toselect fields
133    */
134   public abstract void selectIn(AlignFrame alf, String sequenceIds,
135           String columns);
136
137   /**
138    * select regions of the given alignment frame
139    * 
140    * @param alf
141    * @param toselect
142    *          String separated list { column range, seq1...seqn sequence ids }
143    * @param sep
144    *          separator between toselect fields
145    */
146   public abstract void selectIn(AlignFrame alf, String sequenceIds,
147           String columns, String sep);
148
149   /**
150    * get sequences selected in current alignFrame and return their alignment in
151    * format 'format' either with or without suffix
152    * 
153    * @param alf
154    *          - where selection is
155    * @param format
156    *          - format of alignment file
157    * @param suffix
158    *          - "true" to append /start-end string to each sequence ID
159    * @return selected sequences as flat file or empty string if there was no
160    *         current selection
161    */
162   public abstract String getSelectedSequencesAsAlignment(String format,
163           String suffix);
164
165   /**
166    * get sequences selected in alf and return their alignment in format 'format'
167    * either with or without suffix
168    * 
169    * @param alf
170    *          - where selection is
171    * @param format
172    *          - format of alignment file
173    * @param suffix
174    *          - "true" to append /start-end string to each sequence ID
175    * @return selected sequences as flat file or empty string if there was no
176    *         current selection
177    */
178   public abstract String getSelectedSequencesAsAlignmentFrom(
179           AlignFrame alf, String format, String suffix);
180
181   /**
182    * get a separator separated list of sequence IDs reflecting the order of the
183    * current alignment
184    * 
185    * @return
186    */
187   public abstract String getAlignmentOrder();
188
189   /**
190    * get a separator separated list of sequence IDs reflecting the order of the
191    * alignment in alf
192    * 
193    * @param alf
194    * @return
195    */
196   public abstract String getAlignmentOrderFrom(AlignFrame alf);
197
198   /**
199    * get a sep separated list of sequence IDs reflecting the order of the
200    * alignment in alf
201    * 
202    * @param alf
203    * @param sep
204    *          - separator to use
205    * @return
206    */
207   public abstract String getAlignmentOrderFrom(AlignFrame alf, String sep);
208
209   /**
210    * re-order the current alignment using the given list of sequence IDs
211    * 
212    * @param order
213    *          - sep separated list
214    * @param undoName
215    *          - string to use when referring to ordering action in undo buffer
216    * @return 'true' if alignment was actually reordered. empty string if
217    *         alignment did not contain sequences.
218    */
219   public abstract String orderBy(String order, String undoName);
220
221   /**
222    * re-order the current alignment using the given list of sequence IDs
223    * separated by sep
224    * 
225    * @param order
226    *          - sep separated list
227    * @param undoName
228    *          - string to use when referring to ordering action in undo buffer
229    * @param sep
230    * @return 'true' if alignment was actually reordered. empty string if
231    *         alignment did not contain sequences.
232    */
233   public abstract String orderBy(String order, String undoName, String sep);
234
235   /**
236    * re-order the given alignment using the given list of sequence IDs separated
237    * by sep
238    * 
239    * @param alf
240    * @param order
241    *          - sep separated list
242    * @param undoName
243    *          - string to use when referring to ordering action in undo buffer
244    * @param sep
245    * @return 'true' if alignment was actually reordered. empty string if
246    *         alignment did not contain sequences.
247    */
248   public abstract String orderAlignmentBy(AlignFrame alf, String order,
249           String undoName, String sep);
250
251   /**
252    * get alignment as format (format names FASTA, BLC, CLUSTAL, MSF, PILEUP,
253    * PFAM - see jalview.io.AppletFormatAdapter for full list)
254    * 
255    * @param format
256    * @return
257    */
258   public abstract String getAlignment(String format);
259
260   /**
261    * get alignment displayed in alf as format
262    * 
263    * @param alf
264    * @param format
265    * @return
266    */
267   public abstract String getAlignmentFrom(AlignFrame alf, String format);
268
269   /**
270    * get alignment as format with jalview start-end sequence suffix appended
271    * 
272    * @param format
273    * @param suffix
274    * @return
275    */
276   public abstract String getAlignment(String format, String suffix);
277
278   /**
279    * get alignment displayed in alf as format with or without the jalview
280    * start-end sequence suffix appended
281    * 
282    * @param alf
283    * @param format
284    * @param suffix
285    * @return
286    */
287   public abstract String getAlignmentFrom(AlignFrame alf, String format,
288           String suffix);
289
290   /**
291    * add the given features or annotation to the current alignment
292    * 
293    * @param annotation
294    */
295   public abstract void loadAnnotation(String annotation);
296
297   /**
298    * add the given features or annotation to the given alignment view
299    * 
300    * @param alf
301    * @param annotation
302    */
303   public abstract void loadAnnotationFrom(AlignFrame alf, String annotation);
304
305   /**
306    * parse the given string as a jalview feature or GFF annotation file and
307    * optionally enable feature display on the current alignFrame
308    * 
309    * @param features
310    *          - gff or features file
311    * @param autoenabledisplay
312    *          - when true, feature display will be enabled if any features can
313    *          be parsed from the string.
314    */
315   public abstract void loadFeatures(String features,
316           boolean autoenabledisplay);
317
318   /**
319    * parse the given string as a jalview feature or GFF annotation file and
320    * optionally enable feature display on the given alignFrame.
321    * 
322    * @param alf
323    * @param features
324    *          - gff or features file
325    * @param autoenabledisplay
326    *          - when true, feature display will be enabled if any features can
327    *          be parsed from the string.
328    * @return true if data parsed as features
329    */
330   public abstract boolean loadFeaturesFrom(AlignFrame alf, String features,
331           boolean autoenabledisplay);
332
333   /**
334    * get the sequence features in the given format (Jalview or GFF)
335    * 
336    * @param format
337    * @return
338    */
339   public abstract String getFeatures(String format);
340
341   /**
342    * get the sequence features in alf in the given format (Jalview or GFF)
343    * 
344    * @param alf
345    * @param format
346    * @return
347    */
348   public abstract String getFeaturesFrom(AlignFrame alf, String format);
349
350   /**
351    * get current alignment's annotation as an annotation file
352    * 
353    * @return
354    */
355   public abstract String getAnnotation();
356
357   /**
358    * get alignment view alf's annotation as an annotation file
359    * 
360    * @param alf
361    * @return
362    */
363   public abstract String getAnnotationFrom(AlignFrame alf);
364
365   /**
366    * create a new view and return the alignFrame instance
367    * 
368    * @return
369    */
370   public abstract AlignFrame newView();
371
372   /**
373    * create a new view named name and return the alignFrame instance
374    * 
375    * @param name
376    * @return
377    */
378   public abstract AlignFrame newView(String name);
379
380   /**
381    * create a new view on alf and return the alignFrame instance
382    * 
383    * @param alf
384    * @return
385    */
386   public abstract AlignFrame newViewFrom(AlignFrame alf);
387
388   /**
389    * create a new view named name on alf
390    * 
391    * @param alf
392    * @param name
393    * @return
394    */
395   public abstract AlignFrame newViewFrom(AlignFrame alf, String name);
396
397   /**
398    * 
399    * @param text
400    *          alignment file as a string
401    * @param title
402    *          window title
403    * @return null or new alignment frame
404    */
405   public abstract AlignFrame loadAlignment(String text, String title);
406
407   /**
408    * register a javascript function to handle any alignment mouseover events
409    * 
410    * @param listener
411    *          name of javascript function (called with arguments
412    *          [jalview.appletgui.AlignFrame,String(sequence id),String(column in
413    *          alignment), String(position in sequence)]
414    */
415   public abstract void setMouseoverListener(String listener);
416
417   /**
418    * register a javascript function to handle mouseover events
419    * 
420    * @param af
421    *          (null or specific alignframe for which events are to be listened
422    *          for)
423    * @param listener
424    *          name of javascript function
425    */
426   public abstract void setMouseoverListener(AlignFrame af, String listener);
427
428   /**
429    * register a javascript function to handle any alignment selection events.
430    * Events are generated when the user completes a selection event, or when the
431    * user deselects all selected regions.
432    * 
433    * @param listener
434    *          name of javascript function (called with arguments
435    *          [jalview.appletgui.AlignFrame, String(sequence set id),
436    *          String(separator separated list of sequences which were selected),
437    *          String(separator separated list of column ranges (i.e. single
438    *          number or hyphenated range) that were selected)]
439    */
440   public abstract void setSelectionListener(String listener);
441
442   public abstract void setSelectionListener(AlignFrame af, String listener);
443
444   /**
445    * register a javascript function to handle events normally routed to a Jmol
446    * structure viewer.
447    * 
448    * @param listener
449    *          - javascript function (arguments are variable, see
450    *          jalview.javascript.MouseOverStructureListener for full details)
451    * @param modelSet
452    *          - separator separated list of PDB file URIs that this viewer is
453    *          handling. These files must be in the same order they appear in
454    *          Jmol (e.g. first one is frame 1, second is frame 2, etc).
455    * @see jalview.javascript.MouseOverStructureListener
456    */
457   public abstract void setStructureListener(String listener, String modelSet);
458
459   /**
460    * remove any callback using the given listener function and associated with
461    * the given alignFrame (or null for all callbacks)
462    * 
463    * @param af
464    *          (may be null)
465    * @param listener
466    *          (may be null)
467    */
468   public abstract void removeJavascriptListener(AlignFrame af,
469           String listener);
470
471   /**
472    * send a mouseover message to all the alignment windows associated with the
473    * given residue in the pdbfile
474    * 
475    * @param pdbResNum
476    * @param chain
477    * @param pdbfile
478    */
479   public abstract void mouseOverStructure(String pdbResNum, String chain,
480           String pdbfile);
481
482   /**
483    * bind a pdb file to a sequence in the given alignFrame.
484    * 
485    * @param alFrame
486    *          - null or specific alignFrame. This specifies the dataset that
487    *          will be searched for a seuqence called sequenceId
488    * @param sequenceId
489    *          - sequenceId within the dataset.
490    * @param pdbEntryString
491    *          - the short name for the PDB file
492    * @param pdbFile
493    *          - pdb file - either a URL or a valid PDB file.
494    * @return true if binding was as success TODO: consider making an exception
495    *         structure for indicating when PDB parsing or sequenceId location
496    *         fails.
497    */
498   public abstract boolean addPdbFile(AlignFrame alFrame, String sequenceId,
499           String pdbEntryString, String pdbFile);
500
501   /**
502    * adjust horizontal/vertical scroll to make the given location the top left
503    * hand corner for the given view
504    * 
505    * @param alf
506    * @param topRow
507    * @param leftHandColumn
508    */
509   public abstract void scrollViewToIn(AlignFrame alf, String topRow,
510           String leftHandColumn);
511
512   /**
513    * adjust vertical scroll to make the given row the top one for given view
514    * 
515    * @param alf
516    * @param topRow
517    */
518   public abstract void scrollViewToRowIn(AlignFrame alf, String topRow);
519
520   /**
521    * adjust horizontal scroll to make the given column the left one in the given
522    * view
523    * 
524    * @param alf
525    * @param leftHandColumn
526    */
527   public abstract void scrollViewToColumnIn(AlignFrame alf,
528           String leftHandColumn);
529
530   /**
531    * 
532    * @return
533    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
534    */
535   public abstract String getFeatureGroups();
536
537   /**
538    * @param alf
539    *          alignframe to get feature groups on
540    * @return
541    * @see jalview.appletgui.AlignFrame#getFeatureGroups()
542    */
543   public abstract String getFeatureGroupsOn(AlignFrame alf);
544
545   /**
546    * @param visible
547    * @return
548    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
549    */
550   public abstract String getFeatureGroupsOfState(boolean visible);
551
552   /**
553    * @param alf
554    *          align frame to get groups of state visible
555    * @param visible
556    * @return
557    * @see jalview.appletgui.AlignFrame#getFeatureGroupsOfState(boolean)
558    */
559   public abstract String getFeatureGroupsOfStateOn(AlignFrame alf,
560           boolean visible);
561
562   /**
563    * @param groups
564    *          tab separated list of group names
565    * @param state
566    *          true or false
567    * @see jalview.appletgui.AlignFrame#setFeatureGroupState(java.lang.String[],
568    *      boolean)
569    */
570   public abstract void setFeatureGroupStateOn(AlignFrame alf,
571           String groups, boolean state);
572
573   public abstract void setFeatureGroupState(String groups, boolean state);
574
575   /**
576    * List separator string
577    * 
578    * @return the separator
579    */
580   public abstract String getSeparator();
581
582   /**
583    * List separator string
584    * 
585    * @param separator
586    *          the separator to set. empty string will reset separator to default
587    */
588   public abstract void setSeparator(String separator);
589
590   /**
591    * Retrieve fragments of a large packet of data made available by JalviewLite.
592    * 
593    * @param messageclass
594    * @param viewId
595    * @return next chunk of message
596    */
597   public abstract String getJsMessage(String messageclass, String viewId);
598
599 }